Skip to main content

Contributing

Before Starting​

  1. Read the Architecture Overview.
  2. Check the engineering roadmap in design/30-slices.md at the directory.
  3. Check documentation work in Documentation Roadmap.
  4. Confirm an open pull request does not already address the same change.

Change Scope​

Keep pull requests reviewable:

  • one coherent behavior or documentation milestone;
  • tests beside behavior changes;
  • documentation beside public contract changes;
  • no unrelated formatting churn; and
  • no generated artifacts unless the directory explicitly tracks them.

Use a feature/ branch for planned work.

PowerShell Style​

  • Target PowerShell 7.4.
  • Use approved verbs and Verb-Noun public names.
  • Enable strict mode in standalone build scripts.
  • Prefer literal paths for filesystem operations.
  • Preserve deterministic ordinal ordering.
  • Emit UTF-8 without BOM for generated text.
  • Never embed local absolute paths in generated source.
  • Keep Build-PSModule orchestration-only.

Run these from the directory:

./build/Invoke-Quality.ps1 -InstallDependencies

Documentation Checks​

Changes to any Markdown file should pass the link and terminology gate:

./build/Test-Documentation.ps1

Tests​

Behavior changes require focused Pester coverage:

Invoke-Pester -Path ./tests -Output Detailed

Changes to packaging, manifests, minimum runtime behavior, runtime mappings, or container installation should also run the relevant scripts:

./build/Test-PowerShellBaseline.ps1
./build/Test-GeneratorNuGetPackage.ps1

Run the Docker end-to-end suite when container behavior changes.

Inspector Changes​

For an inspector:

  • define the exact directory input boundary;
  • sort inputs and outputs deterministically;
  • respect common path exclusions;
  • preserve relative /-separated paths;
  • add empty-input and representative-input fixtures;
  • add malformed-input coverage; and
  • document the supported subset and output shape.

Do not imply full YAML, JSON Schema, OpenAPI, Dockerfile, or project-system support when the parser intentionally implements a subset.

Plugin Changes​

The plugin context is internal in Version 1. Built-in and local plugin changes must preserve stage boundaries and provide actionable execution diagnostics. Do not present a new context field as stable public API.

Documentation Changes​

Documentation pages use:

  • YAML front matter with title, description, and sidebar_position;
  • one level-one heading matching the page title;
  • relative links;
  • fenced code blocks with a language;
  • Docusaurus admonitions only when they remain understandable in source Markdown;
  • commands runnable from a stated working directory; and
  • implemented behavior only.

Each category contains _category_.json.

Pull Request Checklist​

  • Scope is focused.
  • New behavior has tests.
  • Public behavior has documentation.
  • Quality checks pass.
  • Documentation link and terminology checks pass.
  • Relevant Pester tests pass.
  • Docker or package checks pass when applicable.
  • No secrets, machine paths, or unrelated files are included.
  • The PR description states impact and validation.