Skip to content

Commit 52f3244

Browse files
📖 [Docs]: Process-PSModule runtime settings contract documentation updated (#56)
Process-PSModule documentation now describes the current internal runtime settings contract in evergreen terms while keeping `.github/PSModule.yml` as the user-facing configuration source. ## Changed: Pipeline stages runtime contract documentation - Clarified that Plan enriches `.github/PSModule.yml` into an internal runtime `Settings` object shared between jobs. - Documented the current phase-owned execution flags, test suite matrix locations, and publish resolution paths as the active contract. ## Changed: Runtime settings reference style - Replaced comparison-oriented wording with definitive runtime path documentation (`Settings.*`) and behavior-focused descriptions. - Kept version stamping and release-decision references aligned with `Settings.Publish.Module.Resolution.*`. ## Changed: Usage behavior wording - Updated the important-file behavior section to state the current runtime values declaratively. ## Technical Details - Files updated: - `src/docs/Frameworks/Process-PSModule/pipeline-stages.md` - `src/docs/Frameworks/Process-PSModule/usage.md` - `src/docs/Frameworks/Process-PSModule/configuration.md` - Change is documentation-only and aligned with the current Process-PSModule runtime contract. <details> <summary>Related links</summary> - Upstream runtime contract context: PSModule/Process-PSModule#402 </details> --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
1 parent 6348490 commit 52f3244

3 files changed

Lines changed: 37 additions & 4 deletions

File tree

‎src/docs/Frameworks/Process-PSModule/configuration.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,11 @@ description: The Process-PSModule settings file — every available setting, the
88
The workflow is configured using a settings file in the module repository.
99
The file can be a `JSON`, `YAML`, or `PSD1` file. By default, it will look for `.github/PSModule.yml`.
1010

11+
The settings listed on this page are the user-facing configuration contract in `.github/PSModule.yml`. During the
12+
Plan phase, Process-PSModule enriches this input into an internal runtime `Settings` object that downstream workflows
13+
consume. Internal runtime paths in workflow docs (for example, `Settings.Publish.Module.Resolution.*`) describe that
14+
enriched inter-workflow contract, not a different authoring format for repository settings files.
15+
1116
The following settings are available in the settings file:
1217

1318
| Name | Type | Description | Default |

‎src/docs/Frameworks/Process-PSModule/pipeline-stages.md‎

Lines changed: 31 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,36 @@ implements it.
1515

1616
The Plan job is the single decision point of the workflow. It reads the settings file (`.github/PSModule.yml`),
1717
collects event context from GitHub, and decides what should happen in the rest of the process. Using that
18-
situational awareness, it calculates the next module version. All decisions are captured in a single `Settings`
19-
object — including version data under `Settings.Module` — that every downstream job receives.
18+
situational awareness, it calculates the next module version.
19+
20+
The user-facing settings file stays in `.github/PSModule.yml`. The workflow enriches that input into an internal runtime
21+
`Settings` object passed between jobs. In this runtime contract, execution decisions are phase-owned (`*.Enabled`), test
22+
suite matrices are defined under each owning test phase, and resolved version metadata is stored under
23+
`Settings.Publish.Module.Resolution`.
24+
25+
### Internal runtime settings contract
26+
27+
| Runtime path | Meaning |
28+
| --- | --- |
29+
| `Settings.Linter.Repository.Enabled` | Whether repository linting runs. |
30+
| `Settings.Build.Module.Enabled` | Whether module build runs. |
31+
| `Settings.Test.SourceCode.Enabled` | Whether source-code tests run. |
32+
| `Settings.Test.PSModule.Enabled` | Whether framework tests run. |
33+
| `Settings.Test.Module.BeforeAllEnabled` | Whether setup scripts run before module-local tests. |
34+
| `Settings.Test.Module.MainEnabled` | Whether module-local Pester tests run. |
35+
| `Settings.Test.Module.AfterAllEnabled` | Whether teardown scripts run after module-local tests. |
36+
| `Settings.Test.TestResults.Enabled` | Whether test results aggregation runs. |
37+
| `Settings.Test.CodeCoverage.Enabled` | Whether code coverage aggregation/enforcement runs. |
38+
| `Settings.Publish.Module.Enabled` | Whether module publication/release runs. |
39+
| `Settings.Publish.Site.Enabled` | Whether documentation publication runs. |
40+
| `Settings.Test.SourceCode.Suites` | Source-code test suite matrix. |
41+
| `Settings.Test.PSModule.Suites` | Framework test suite matrix. |
42+
| `Settings.Test.Module.Suites` | Module-local test suite matrix. |
43+
| `Settings.Publish.Module.Resolution.Version` | Resolved semantic version used for build and publish. |
44+
| `Settings.Publish.Module.Resolution.Prerelease` | Whether the resolved version is prerelease. |
45+
| `Settings.Publish.Module.Resolution.FullVersion` | Resolved full version string. |
46+
| `Settings.Publish.Module.Resolution.ReleaseType` | Resolved release classification for this run. |
47+
| `Settings.Publish.Module.Resolution.CreateRelease` | Whether this run creates a release. |
2048

2149
## Lint-Repository
2250

@@ -26,7 +54,7 @@ object — including version data under `Settings.Module` — that every downstr
2654

2755
[workflow](https://github.com/PSModule/Process-PSModule/blob/main/.github/workflows/Build-Module.yml)
2856

29-
- Compiles the module source code into a PowerShell module, stamping the version from `Settings.Module` into the manifest.
57+
- Compiles the module source code into a PowerShell module, stamping the version from `Settings.Publish.Module.Resolution.Version` into the manifest.
3058
- Uploads the built artifact.
3159

3260
## Test source code

‎src/docs/Frameworks/Process-PSModule/usage.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -291,7 +291,7 @@ When a pull request does not contain changes to important files:
291291

292292
1. A comment is automatically added to the PR listing the configured patterns and explaining why build/test stages are
293293
skipped
294-
2. `Settings.Module.ReleaseType` is set to `None` (and `Settings.Module.CreateRelease` is `false`)
294+
2. `Settings.Publish.Module.Resolution.ReleaseType` is `None` (and `Settings.Publish.Module.Resolution.CreateRelease` is `false`)
295295
3. Build, test, and publish stages are skipped
296296
4. The PR can still be merged for non-release changes (documentation updates, CI improvements, etc.)
297297

0 commit comments

Comments
 (0)