CONTRIBUTING.md

title	Contributing

Contributing

Keep contributions focused, readable, and safe for ConfigMgr task sequence use. Follow the code of conduct when discussing changes.

Before opening a pull request:

1. Install the pinned development modules and run .\build\Invoke-Validation.ps1 in Windows PowerShell 5.1 as described in validation.
2. Use generic examples and keep environment-specific values configurable.
3. Keep credentials out of logs and pull requests.
4. Update documentation when behavior changes.
5. Add focused Pester coverage for behavioral fixes, and distinguish mocks from live tests.
6. Regenerate CHECKSUMS.txt after all file changes, including documentation and workflow updates, following the checkout convention. Run validation again before pushing.
7. Check upstream licenses before reusing code or artwork. Preserve copyright, license notices, and required credit for approved reuse.

-SkipChecksums skips only the validator's final manifest verification phase. Repository checksum tests still run, so the switch does not permit a complete validation run with a stale manifest. Regenerate CHECKSUMS.txt before running the complete validator, and omit the switch for final validation.

The production PowerShell script must remain self-contained, target Windows PowerShell 5.1, and retain secure defaults. Review analyzer warnings individually; any suppression needs a precise justification. Never include credentials or unsanitized logs in a pull request.

Record live environment results separately from static analysis and mocked tests. A regular release identifies a distribution, not a live-certified platform; earlier results do not validate later changes. Follow the release process, keep published artifacts unchanged, and use a new version for changed release content.

Source conventions

• Use four-space indentation for PowerShell and two spaces for YAML and JSON. Preserve existing SVG formatting; regenerate banners through the shared banner workflow. Follow .gitattributes: CRLF for .ps1, LF for other maintained text.
• Start production scripts and build helpers with #Requires -Version 5.1, followed by one blank line before comment-based help. Keep help before CmdletBinding, suppression attributes, and param. Check both AST-associated help and nonexecuting Get-Help -Full.
• Use the pinned PSScriptAnalyzer formatter for spacing and indentation. Review formatting separately from behavioral changes: preserve non-comment tokens, AST structure, requirements, literal strings, defaults, security decisions, and output streams.
• Indent Pester setup and nested test blocks to reflect their scope. Preserve fixture contents, assertions, and process timeouts. Comments should explain non-obvious constraints, not restate the code.
• Use Windows PowerShell 5.1, PowerShell 7, and PowerShell script consistently. Use Configuration Manager or ConfigMgr for the product, and lowercase task sequence in prose. Preserve exact UI labels.
• Use sentence-case headings and active verbs. Lead with the operator's next step and keep instructions concise, following Microsoft's style and voice guidance.
• Describe the tools and actions the reader needs. Include restrictions when they prevent mistakes, protect data, or explain a supported-runtime boundary; omit inventories of unrelated tools.
• Keep explicit front matter on contributor and conduct pages so Jekyll renders them, and retain the examples index's /examples/ permalink. Use relative .md links in Markdown and final .html URLs in Pages navigation.

Keep diagrams static and self-contained, with Segoe UI/system sans-serif typography, the project's blue/teal palette, and legible light/dark surfaces. Separate step numbers from labels and target text contrast of at least 4.5:1, or 3:1 for large text. Retain meaningful titles, descriptions, explicit pending-status text, equivalent prose, and full-size links; use compact workflow variants when narrow layouts need them. Illustrations are never evidence of a test pass.