Skip to main content

Development Overview

This page documents the current development workflow for HaloAPI.

Quick Start​

pwsh -File .\Bootstrap.ps1
pwsh -File .\DevOps\Quality\run-pssa.ps1
pwsh -File .\DevOps\Quality\test.ps1 -Suite Meta

Repo Layout​

  • Public/ contains exported cmdlets.
  • Private/ contains internal helpers.
  • Classes/ contains helper classes, validators, completers, and argument transformations.
  • Tests/ contains Pester suites.
  • DevOps/Quality/ contains static-analysis and test entrypoints.
  • Docs/HaloAPI/development/ contains repo-authored development documentation.
  • docs/HaloAPI/ is the canonical generated and curated publishable docs layout.

Development Process​

HaloAPI uses GitHub Actions for CI and release automation. Keep workflow changes explicit and small.

Normal contribution flow should target develop. Treat main as the stable release branch.

For normal local validation, prefer the dedicated repo scripts:

pwsh -File .\Bootstrap.ps1
pwsh -File .\DevOps\Quality\run-pssa.ps1
pwsh -File .\DevOps\Quality\test.ps1 -Suite Meta

For interactive VS Code runs, prefer the Test HaloAPI task or:

pwsh -File .\DevOps\Quality\test.ps1 -IncludeVSCodeMarker

Do not invoke Invoke-Pester directly as the normal validation path in the VS Code host, terminal, or automation. Use DevOps\Quality\test.ps1 as the supported test entrypoint.

Quality Gates​

  • Run Bootstrap.ps1 after changing local dependencies.
  • Run run-pssa.ps1 to validate PowerShell style and custom repo rules.
  • Run test.ps1 -Suite Meta for the safe baseline test suite.
  • Only run Live tests when the required Halo testing environment variables are available.

Manual E2E Workflow​

Destructive end-to-end tests are executed through a dedicated manual workflow.

Workflow: Manual E2E Tests Path: .github/workflows/manual-e2e-tests.yml

Run steps:

  1. Open Actions in GitHub and select Manual E2E Tests.
  2. Click Run workflow.
  3. Set confirm_destructive to true.
  4. Run the workflow and review published Pester Tests (E2E) results.

Notes:

  • The workflow requires Halo test secrets (HaloTestingURL, HaloTestingClientID, HaloTestingClientSecret, HaloTestingTenant).
  • The workflow runs DevOps\Quality\test.ps1 -Suite E2E and uploads .artifacts/TestResults.e2e.xml.
  • Keep E2E runs manual/on-demand to avoid destructive test execution in normal PR CI.

Release and Workflow Notes​

  • Keep GitHub Actions changes focused and explicit.
  • Preserve PowerShell Gallery publishing behavior when changing release automation.
  • Stable tags must be reachable from main; prerelease tags may be cut from develop.
  • Development docs are synced from Docs/HaloAPI/development to homotechsualdocs/docs/haloapi/development after successful develop pushes.
Last updated on by GitHub Action