Skip to content

AGENTS.md

Latest commit

 

History

History
67 lines (51 loc) · 3.49 KB

AGENTS.md

File metadata and controls

67 lines (51 loc) · 3.49 KB
Raw

AGENTS.md

Coding

Write code for PowerShell 5.1 only.

Prefer boring code that a reviewer can easily understand. Bias toward simplicity over compactness, cleverness, speed, or elegance. Make all dependencies as clear as possible. Avoid splatting unless it makes code substantially clearer. Avoid backtick line continuations. Avoid calling external shells/tools. Avoid using COM objects unless they are obviously read-only. Avoid clever pipelines if a loop is easier to audit. Avoid non-ASCII literals in PowerShell source files. Build required Unicode characters with [char] or [char]::ConvertFromUtf32() so Windows PowerShell 5.1 and GitHub Actions read the source consistently.

Code outside the installer/updater must not change computer state. Saving useful and temporary files that are not larger than 100MB is OK.

Testing

Run tests from the repository root in Windows PowerShell (v5).

  1. Fast unit checks: 
    .\tests\run-unit-tests.ps1

Runs the Pester suite under tests/Unit. This is the default check for most code changes. This is usually enough for a small pure-unit change. Also use it if you add or modify Pester tests.

.\tests\run-all-tests.ps1 -Smoke now includes the repo-wide PowerShell syntax pass automatically. You can still run it directly if you only want the parser check:

.\scripts\syntax\Test-RepoPowerShellSyntax.ps1

It parses all tracked .ps1 files except generated content under .git and temp, and caches file timestamps so later runs only re-check changed files.

  1. Quick smoke coverage:
.\tests\run-all-tests.ps1 -Smoke

Runs a small, fast subset intended for quick validation, including the repo-wide PowerShell syntax pass. Use this at minimum if you touch installer code, service-path resolution, or machine-environment behavior.

  1. Broader integration coverage when the change affects machine-coupled behavior: 
    .\tests\run-all-tests.ps1 -Category Integration

Runs machine-coupled checks and standalone test scripts. Use this when changes touch broader runtime behavior, service resolution, installer behavior, or environment-dependent logic.

  1. Full repo test pass:
.\tests\run-all-tests.ps1

Runs the full combined test selection, including syntax parsing and ScriptAnalyzer. .\tests\run-all-tests.ps1 -Detailed is the same as the full run, but prints extra detail and artifact locations.

Notes

  • Pester 5 or newer must be installed. .\tests\run-unit-tests.ps1 checks this explicitly.
  • Prefer the repo test runners over calling Invoke-Pester directly.
  • If a full or integration run fails only because of sandbox or host restrictions, report that clearly instead of treating it as a product regression.

Releases

  • Use .\scripts\release\New-GetComputerHealthRelease.ps1 from the repo root to create a release. It defaults to a minor bump; use -Part Patch or -Part Major to change the semantic-version part being incremented.
  • Use .\scripts\release\New-GetComputerHealthRelease.ps1 -SkipTests only when the relevant tests have already passed in the current work session and you want to avoid rerunning the unit and smoke wrappers during release. The release script still validates installation from the release zip.

For minor & major releases verify the "List of Available Tests" in README.md matches what Get-ComputerHealth -ListAllBuiltInTests returns. If not, update README.md