From 239ffe4430a185b9df5b3cffa54f917ad61dd654 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Sat, 18 Jul 2026 20:22:10 +0200 Subject: [PATCH 1/2] Document phase-owned runtime settings contract Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../Process-PSModule/configuration.md | 5 +++ .../Process-PSModule/pipeline-stages.md | 33 +++++++++++++++++-- src/docs/Frameworks/Process-PSModule/usage.md | 2 +- 3 files changed, 36 insertions(+), 4 deletions(-) diff --git a/src/docs/Frameworks/Process-PSModule/configuration.md b/src/docs/Frameworks/Process-PSModule/configuration.md index be83e1d..71af957 100644 --- a/src/docs/Frameworks/Process-PSModule/configuration.md +++ b/src/docs/Frameworks/Process-PSModule/configuration.md @@ -8,6 +8,11 @@ description: The Process-PSModule settings file — every available setting, the The workflow is configured using a settings file in the module repository. The file can be a `JSON`, `YAML`, or `PSD1` file. By default, it will look for `.github/PSModule.yml`. +The settings listed on this page are the user-facing configuration contract in `.github/PSModule.yml`. During the +Plan phase, Process-PSModule enriches this input into an internal runtime `Settings` object that downstream workflows +consume. Internal runtime paths in workflow docs (for example, `Settings.Publish.Module.Resolution.*`) describe that +enriched inter-workflow contract, not a different authoring format for repository settings files. + The following settings are available in the settings file: | Name | Type | Description | Default | diff --git a/src/docs/Frameworks/Process-PSModule/pipeline-stages.md b/src/docs/Frameworks/Process-PSModule/pipeline-stages.md index 8d8c320..657fedf 100644 --- a/src/docs/Frameworks/Process-PSModule/pipeline-stages.md +++ b/src/docs/Frameworks/Process-PSModule/pipeline-stages.md @@ -15,8 +15,35 @@ implements it. The Plan job is the single decision point of the workflow. It reads the settings file (`.github/PSModule.yml`), collects event context from GitHub, and decides what should happen in the rest of the process. Using that -situational awareness, it calculates the next module version. All decisions are captured in a single `Settings` -object — including version data under `Settings.Module` — that every downstream job receives. +situational awareness, it calculates the next module version. + +The user-facing settings file shape stays under `.github/PSModule.yml`. The workflow then enriches that input into +an internal runtime `Settings` object passed between jobs. In that runtime object, execution decisions are phase-owned +(`*.Enabled`) and resolved module version metadata is under `Settings.Publish.Module.Resolution`. + +### Internal runtime contract mapping (old -> new) + +| Previous internal path | Current internal path | +| --- | --- | +| `Settings.Run.LinterRepository` | `Settings.Linter.Repository.Enabled` | +| `Settings.Run.BuildModule` | `Settings.Build.Module.Enabled` | +| `Settings.Run.TestSourceCode` | `Settings.Test.SourceCode.Enabled` | +| `Settings.Run.TestPSModule` | `Settings.Test.PSModule.Enabled` | +| `Settings.Run.TestModuleBeforeAll` | `Settings.Test.Module.BeforeAllEnabled` | +| `Settings.Run.TestModule` | `Settings.Test.Module.MainEnabled` | +| `Settings.Run.TestModuleAfterAll` | `Settings.Test.Module.AfterAllEnabled` | +| `Settings.Run.GetTestResults` | `Settings.Test.TestResults.Enabled` | +| `Settings.Run.GetCodeCoverage` | `Settings.Test.CodeCoverage.Enabled` | +| `Settings.Run.PublishModule` | `Settings.Publish.Module.Enabled` | +| `Settings.Run.PublishSite` | `Settings.Publish.Site.Enabled` | +| `Settings.TestSuites.SourceCode` | `Settings.Test.SourceCode.Suites` | +| `Settings.TestSuites.PSModule` | `Settings.Test.PSModule.Suites` | +| `Settings.TestSuites.Module` | `Settings.Test.Module.Suites` | +| `Settings.Module.Version` | `Settings.Publish.Module.Resolution.Version` | +| `Settings.Module.Prerelease` | `Settings.Publish.Module.Resolution.Prerelease` | +| `Settings.Module.FullVersion` | `Settings.Publish.Module.Resolution.FullVersion` | +| `Settings.Module.ReleaseType` | `Settings.Publish.Module.Resolution.ReleaseType` | +| `Settings.Module.CreateRelease` | `Settings.Publish.Module.Resolution.CreateRelease` | ## Lint-Repository @@ -26,7 +53,7 @@ object — including version data under `Settings.Module` — that every downstr [workflow](https://github.com/PSModule/Process-PSModule/blob/main/.github/workflows/Build-Module.yml) -- Compiles the module source code into a PowerShell module, stamping the version from `Settings.Module` into the manifest. +- Compiles the module source code into a PowerShell module, stamping the version from `Settings.Publish.Module.Resolution.Version` into the manifest. - Uploads the built artifact. ## Test source code diff --git a/src/docs/Frameworks/Process-PSModule/usage.md b/src/docs/Frameworks/Process-PSModule/usage.md index 5e7f7b9..1ef55b0 100644 --- a/src/docs/Frameworks/Process-PSModule/usage.md +++ b/src/docs/Frameworks/Process-PSModule/usage.md @@ -291,7 +291,7 @@ When a pull request does not contain changes to important files: 1. A comment is automatically added to the PR listing the configured patterns and explaining why build/test stages are skipped -2. `Settings.Module.ReleaseType` is set to `None` (and `Settings.Module.CreateRelease` is `false`) +2. The internal runtime object sets `Settings.Publish.Module.Resolution.ReleaseType` to `None` (and `Settings.Publish.Module.Resolution.CreateRelease` to `false`) 3. Build, test, and publish stages are skipped 4. The PR can still be merged for non-release changes (documentation updates, CI improvements, etc.) From 5b572a3a8e7c82647457b6c7b5e2fbb9821b057b Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Sat, 18 Jul 2026 20:31:50 +0200 Subject: [PATCH 2/2] Make Process-PSModule docs evergreen Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../Process-PSModule/pipeline-stages.md | 49 ++++++++++--------- src/docs/Frameworks/Process-PSModule/usage.md | 2 +- 2 files changed, 26 insertions(+), 25 deletions(-) diff --git a/src/docs/Frameworks/Process-PSModule/pipeline-stages.md b/src/docs/Frameworks/Process-PSModule/pipeline-stages.md index 657fedf..a786755 100644 --- a/src/docs/Frameworks/Process-PSModule/pipeline-stages.md +++ b/src/docs/Frameworks/Process-PSModule/pipeline-stages.md @@ -17,33 +17,34 @@ The Plan job is the single decision point of the workflow. It reads the settings collects event context from GitHub, and decides what should happen in the rest of the process. Using that situational awareness, it calculates the next module version. -The user-facing settings file shape stays under `.github/PSModule.yml`. The workflow then enriches that input into -an internal runtime `Settings` object passed between jobs. In that runtime object, execution decisions are phase-owned -(`*.Enabled`) and resolved module version metadata is under `Settings.Publish.Module.Resolution`. +The user-facing settings file stays in `.github/PSModule.yml`. The workflow enriches that input into an internal runtime +`Settings` object passed between jobs. In this runtime contract, execution decisions are phase-owned (`*.Enabled`), test +suite matrices are defined under each owning test phase, and resolved version metadata is stored under +`Settings.Publish.Module.Resolution`. -### Internal runtime contract mapping (old -> new) +### Internal runtime settings contract -| Previous internal path | Current internal path | +| Runtime path | Meaning | | --- | --- | -| `Settings.Run.LinterRepository` | `Settings.Linter.Repository.Enabled` | -| `Settings.Run.BuildModule` | `Settings.Build.Module.Enabled` | -| `Settings.Run.TestSourceCode` | `Settings.Test.SourceCode.Enabled` | -| `Settings.Run.TestPSModule` | `Settings.Test.PSModule.Enabled` | -| `Settings.Run.TestModuleBeforeAll` | `Settings.Test.Module.BeforeAllEnabled` | -| `Settings.Run.TestModule` | `Settings.Test.Module.MainEnabled` | -| `Settings.Run.TestModuleAfterAll` | `Settings.Test.Module.AfterAllEnabled` | -| `Settings.Run.GetTestResults` | `Settings.Test.TestResults.Enabled` | -| `Settings.Run.GetCodeCoverage` | `Settings.Test.CodeCoverage.Enabled` | -| `Settings.Run.PublishModule` | `Settings.Publish.Module.Enabled` | -| `Settings.Run.PublishSite` | `Settings.Publish.Site.Enabled` | -| `Settings.TestSuites.SourceCode` | `Settings.Test.SourceCode.Suites` | -| `Settings.TestSuites.PSModule` | `Settings.Test.PSModule.Suites` | -| `Settings.TestSuites.Module` | `Settings.Test.Module.Suites` | -| `Settings.Module.Version` | `Settings.Publish.Module.Resolution.Version` | -| `Settings.Module.Prerelease` | `Settings.Publish.Module.Resolution.Prerelease` | -| `Settings.Module.FullVersion` | `Settings.Publish.Module.Resolution.FullVersion` | -| `Settings.Module.ReleaseType` | `Settings.Publish.Module.Resolution.ReleaseType` | -| `Settings.Module.CreateRelease` | `Settings.Publish.Module.Resolution.CreateRelease` | +| `Settings.Linter.Repository.Enabled` | Whether repository linting runs. | +| `Settings.Build.Module.Enabled` | Whether module build runs. | +| `Settings.Test.SourceCode.Enabled` | Whether source-code tests run. | +| `Settings.Test.PSModule.Enabled` | Whether framework tests run. | +| `Settings.Test.Module.BeforeAllEnabled` | Whether setup scripts run before module-local tests. | +| `Settings.Test.Module.MainEnabled` | Whether module-local Pester tests run. | +| `Settings.Test.Module.AfterAllEnabled` | Whether teardown scripts run after module-local tests. | +| `Settings.Test.TestResults.Enabled` | Whether test results aggregation runs. | +| `Settings.Test.CodeCoverage.Enabled` | Whether code coverage aggregation/enforcement runs. | +| `Settings.Publish.Module.Enabled` | Whether module publication/release runs. | +| `Settings.Publish.Site.Enabled` | Whether documentation publication runs. | +| `Settings.Test.SourceCode.Suites` | Source-code test suite matrix. | +| `Settings.Test.PSModule.Suites` | Framework test suite matrix. | +| `Settings.Test.Module.Suites` | Module-local test suite matrix. | +| `Settings.Publish.Module.Resolution.Version` | Resolved semantic version used for build and publish. | +| `Settings.Publish.Module.Resolution.Prerelease` | Whether the resolved version is prerelease. | +| `Settings.Publish.Module.Resolution.FullVersion` | Resolved full version string. | +| `Settings.Publish.Module.Resolution.ReleaseType` | Resolved release classification for this run. | +| `Settings.Publish.Module.Resolution.CreateRelease` | Whether this run creates a release. | ## Lint-Repository diff --git a/src/docs/Frameworks/Process-PSModule/usage.md b/src/docs/Frameworks/Process-PSModule/usage.md index 1ef55b0..eeb045a 100644 --- a/src/docs/Frameworks/Process-PSModule/usage.md +++ b/src/docs/Frameworks/Process-PSModule/usage.md @@ -291,7 +291,7 @@ When a pull request does not contain changes to important files: 1. A comment is automatically added to the PR listing the configured patterns and explaining why build/test stages are skipped -2. The internal runtime object sets `Settings.Publish.Module.Resolution.ReleaseType` to `None` (and `Settings.Publish.Module.Resolution.CreateRelease` to `false`) +2. `Settings.Publish.Module.Resolution.ReleaseType` is `None` (and `Settings.Publish.Module.Resolution.CreateRelease` is `false`) 3. Build, test, and publish stages are skipped 4. The PR can still be merged for non-release changes (documentation updates, CI improvements, etc.)