Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
69 lines (55 loc) · 3.69 KB

CONTRIBUTING.md

File metadata and controls

69 lines (55 loc) · 3.69 KB
Raw

Contributing

Thank you for looking. Issues and pull requests are welcome.

Before you start

  • A rule fires on something Intune tolerates, or misses something it does not: that is the most useful issue this project can get. Open one with the script (or a cut-down version that still shows it), the script type, and what Intune actually did on a device. Every rule cites its Evidence, ending in experiment ids such as REM-EXIT-2; those are the entries in Validation/Experiments.psd1 whose results Validation/Findings.md records, so say which finding you think is wrong.
  • A harness result that differs from the portal: include -Verbose output and the result object. Output and ExitCode on it are the values Intune reports; the portal only formats them.
  • A change: open an issue first if it is more than a fix, so the shape can be agreed before the work. CLAUDE.md lists the invariants that look arbitrary until you know the reason.

The conventions

General PowerShell conventions - module layout, comment-based help, Pester, error handling - are mirrored into .github/ from ai-powershell-standards. Those paths are overwritten on every sync, so a change to a convention belongs upstream.

Everything specific to this module is in CLAUDE.md. The ones most often tripped over:

  • A rule is backed by what a device did, not by what a document says. A new rule needs an experiment in Validation/Experiments.psd1, a run recorded in Validation/Findings.md, and the experiment ids in its Evidence.
  • Only exported functions carry .EXTERNALHELP; their help lives in docs/ and is compiled to en-US/IntuneScriptLab-Help.xml by Build/Build-Help.ps1. Rebuild it in the same change as a docs edit; the help gate compares byte for byte.
  • docs/Rules.md is generated by Build/Build-RuleReference.ps1 and a unit test keeps it current. Rebuild it after changing a rule's message, severity or evidence.
  • A new command goes in the manifest, the Export-ModuleMember list in the root module, the contract test, and docs/.
  • Windows PowerShell 5.1 and PowerShell 7 both have to work, so nothing 7-only anywhere the module loads. The suites run on 5.1 and on Windows on ARM in CI.

The checks

Invoke-Pester ./Tests, ./Validation/Tests               # a few minutes; suites needing elevation,
                                                        # a lab account or PSScriptAnalyzer skip themselves
Invoke-ScriptAnalyzer -Path . -Recurse -Severity Error, Warning -ExcludeRule PSAvoidLongLines
./Build/Build-Help.ps1                                  # after editing docs/
./Build/Build-RuleReference.ps1                         # after changing a rule
./Build/Publish-Module.ps1 -WhatIf                      # the full release rehearsal

Run the unit suites under Windows PowerShell 5.1 as well:

powershell -NoProfile -Command "Invoke-Pester ./Tests/Unit, ./Validation/Tests/Unit"

The suites reach no tenant: every Graph call goes through a mocked seam. A change to what a rule or the harness claims about Intune should also be run against a device you own, and the pull request should say what you ran and what it did. The validation kit under Validation/ is how the existing evidence was produced; it needs a tenant and lab devices of your own and its README explains the rounds.

Pull requests

  • One rule, one command or one concern per pull request.
  • Add or update the tests that pin the behaviour, and a line in CHANGELOG.md under [Unreleased].
  • The quality gates run on every pull request on PowerShell 7, Windows PowerShell 5.1, Windows on ARM, and a case-sensitive filesystem for the help.