Skip to content

Commit bc376d0

Browse files
Entry pages and workflow examples use direct prose (#579)
Entry pages describe the framework's reusable PowerShell modules, GitHub Actions workflows, and task automation in direct, present-tense English. The coverage example states its existing minimum of 80%, and the changed descriptive text uses en-US spelling. No consumer action is needed for these prose edits. <!-- ANNOUNCEMENT STOP --> ## Changed: Entry guidance describes existing automation directly The README and site index use direct descriptions instead of promotional or time-relative wording. The coverage example says `at least 80%` because the existing implementation rejects coverage only when it is below the target. The release guide changes only two descriptive uses of `labelled` to `labeled`. The edits preserve the documented capabilities, supported scope, destinations, examples, and obligations. They do not change the framework, caller interface, configuration, release behavior, or site design. The complete fixed-secret/TestData adoption section stays intact. Its separate source-bound decision remains open in #578. <details> <summary>Technical details</summary> ### Exact delivery source and plan | Item | Identity | | --- | --- | | Repository | `PSModule/Process-PSModule` | | Base | `main` at `64ffb1d87f86bd5d487891fdb140b78385a00531` | | Head | `entry-guidance-prose` at `79bac09b581e80b27bae5dad5d87adffac0ff219` | | Comparison | Four files, 10 insertions, 10 deletions | | First real commit | `93b95eb6935d43c3e350bcdd293e19c128dc7aa3`; this draft opened immediately after that push | | Final state | Five small commits pushed; draft; no auto-merge; no labels | This is a fresh main-based delivery, not an amendment to a proposal or first-pass PR. The owner handback includes the explicit extension for the two adjacent index statements at original lines 80-81. No other paragraph-rewrite permission is inferred from the spelling allowance. The issue plan covers the full ten-page read, pinned writing sources, pre-edit expectations, protection baselines, existing checks, early draft, small commits, live ownership checks before each commit, the source-backed threshold clarification, and the final acceptance record. All scoped implementation and verification work is complete. Merge and issue closure remain separate, future review actions. ### Before/after acceptance evidence [The original pre-edit record](#560 (comment)) records the source, expected edits, protection baseline, and existing checks before repository changes. [The threshold clarification record](#560 (comment)) records the parent review request and the below/equal/above experiment before that follow-up edit. All eight exact replacement expectations pass at the final head. They cover nine matches, including the two release-spelling matches. | Region | Before, at the exact base | After, at the exact head | | --- | --- | --- | | README opening | [Line 3](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/README.md#L3): `corner-stone` paragraph | [Line 3](https://github.com/PSModule/Process-PSModule/blob/79bac09b581e80b27bae5dad5d87adffac0ff219/README.md#L3): a direct core-workflow description; end-to-end GitHub Actions, all five lifecycle capabilities, and the Gallery destination remain. | | Index spelling | [Line 18](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/docs/content/index.md#L18): `behaviour` | [Line 18](https://github.com/PSModule/Process-PSModule/blob/79bac09b581e80b27bae5dad5d87adffac0ff219/docs/content/index.md#L18): `behavior`; the rest of the paragraph and `.github/PSModule.yml` remain unchanged. | | Released adjacent index statements | [Lines 80-81](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/docs/content/index.md#L80-L81): `infuses GitHub ... fullest extent` and `DevOps functionality ... missing` | [Lines 80-81](https://github.com/PSModule/Process-PSModule/blob/79bac09b581e80b27bae5dad5d87adffac0ff219/docs/content/index.md#L80-L81): reusable PowerShell modules, GitHub Actions workflows, and automated module delivery. No shipping, exclusivity, completeness, or enforcement claim is added. | | Index task automation | [Line 83](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/docs/content/index.md#L83): `We empower ... effortlessly ... without distractions` | [Line 83](https://github.com/PSModule/Process-PSModule/blob/79bac09b581e80b27bae5dad5d87adffac0ff219/docs/content/index.md#L83): repeated-task automation lets developers write code for PowerShell solutions; both consumers and contributors remain explicit. | | Index goal-setting link | [Line 85](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/docs/content/index.md#L85): `Where we are headed ...` | [Line 85](https://github.com/PSModule/Process-PSModule/blob/79bac09b581e80b27bae5dad5d87adffac0ff219/docs/content/index.md#L85): a neutral imperative link to the same goal-setting model; link text and destination remain unchanged. | | Index canonical guidance | [Line 89](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/docs/content/index.md#L89): `are now canonical` | [Line 89](https://github.com/PSModule/Process-PSModule/blob/79bac09b581e80b27bae5dad5d87adffac0ff219/docs/content/index.md#L89): `are canonical`; authority and destination remain unchanged. | | Coverage example | [Lines 17-23](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/docs/content/guides/configuring-the-pipeline.md#L17-L23): `will require that code coverage is 80% before passing` | [Lines 17-23](https://github.com/PSModule/Process-PSModule/blob/79bac09b581e80b27bae5dad5d87adffac0ff219/docs/content/guides/configuring-the-pipeline.md#L17-L23): `This example runs all steps and requires at least 80% code coverage to pass.` The exact YAML is unchanged. | | Release-guide spelling | [Lines 22 and 58](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/docs/content/guides/versioning-and-releases.md#L22-L60): `labelled` twice | [Lines 22 and 58](https://github.com/PSModule/Process-PSModule/blob/79bac09b581e80b27bae5dad5d87adffac0ff219/docs/content/guides/versioning-and-releases.md#L22-L60): `labeled` twice; all other release guidance is identical. | The complete changed-file comparison permits only these declared replacements. All other text in those four files remains unchanged, including the index introduction, the development-framework heading/anchor, and every configuration/release example. ### Ten-page review and no-change results All ten pages were read in full. The four changed paths and exact regions are listed above. The other six pages need no correction under the narrow spelling allowance. Their complete file bytes and Git blobs remain unchanged. This is a scoped no-change result, not a claim that every paragraph received an unrestricted rewrite or full STE certification. | Reviewed no-change path | Before and after | Identical blob | | --- | --- | --- | | `docs/content/get-started/index.md` | [Before](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/docs/content/get-started/index.md) / [after](https://github.com/PSModule/Process-PSModule/blob/79bac09b581e80b27bae5dad5d87adffac0ff219/docs/content/get-started/index.md); procedure and outcomes unchanged | `72cc182b8e790c4b5420277d69a61de934a02791` | | `docs/content/get-started/repository-setup.md` | [Before](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/docs/content/get-started/repository-setup.md) / [after](https://github.com/PSModule/Process-PSModule/blob/79bac09b581e80b27bae5dad5d87adffac0ff219/docs/content/get-started/repository-setup.md); setup, permissions, secrets, and caller YAML unchanged | `790cf5eafb2946cad7c61398e7f80c7fcf6cc8a5` | | `docs/content/get-started/your-first-release.md` | [Before](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/docs/content/get-started/your-first-release.md) / [after](https://github.com/PSModule/Process-PSModule/blob/79bac09b581e80b27bae5dad5d87adffac0ff219/docs/content/get-started/your-first-release.md); triggers, labels, and release conditions unchanged | `e8b00fb1c220108790517d151dc59b707d895928` | | `docs/content/guides/calling-the-workflow.md` | [Before](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/docs/content/guides/calling-the-workflow.md) / [after](https://github.com/PSModule/Process-PSModule/blob/79bac09b581e80b27bae5dad5d87adffac0ff219/docs/content/guides/calling-the-workflow.md); whole file unchanged, including the protected complete TestData adoption section | `8e18d7e18025b68a1abd318c115719607d3683c3` | | `docs/content/guides/github-app-authentication.md` | [Before](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/docs/content/guides/github-app-authentication.md) / [after](https://github.com/PSModule/Process-PSModule/blob/79bac09b581e80b27bae5dad5d87adffac0ff219/docs/content/guides/github-app-authentication.md); secret mapping, token scope, and permission ceilings unchanged | `cf35933a019eaf977a8ce39ad940ab809edfe9b5` | | `docs/content/guides/structuring-your-module.md` | [Before](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/docs/content/guides/structuring-your-module.md) / [after](https://github.com/PSModule/Process-PSModule/blob/79bac09b581e80b27bae5dad5d87adffac0ff219/docs/content/guides/structuring-your-module.md); layout, help URLs, dependency rules, and source-tree examples unchanged | `c4f36cf327b9e5f045a02b7d05bbb54e7bb39334` | | Changed path | Base blob | Head blob | | --- | --- | --- | | `README.md` | `c2d2257e3948184ebb8db36268f1c7490e0abcbc` | `924672d74ec5927a3bc4b0591b0311cbd9f4e038` | | `docs/content/index.md` | `02cc155fc51c96deba28eaf9ae1f9e899baf2d97` | `03a57bba4e97779ec2e35b9764f024fcb37ba454` | | `docs/content/guides/configuring-the-pipeline.md` | `b77d4cdf2272ad592234076eec0a48afd692a926` | `ae643ebc87483b2154091fa98a681be35416ae40` | | `docs/content/guides/versioning-and-releases.md` | `fe226002f077d1e0e7a01a01514d8112b3303317` | `7694d507ba5f6b0f1d47bb9f2cf04e23d68a9578` | ### Exact contract-preservation results The session-local, one-off comparison passes against the source tree. No comparison script, prose inventory, enforcement tool, test, or dependency is added to the repository. | Protected surface across the ten pages | Result | | --- | --- | | 25 complete fenced blocks | Byte-identical, including every YAML, command, JSON, tree, and example block | | 66 headings | Identical; no heading, anchor source, or navigation destination changes | | 234 inline-code spans | Identical technical names, paths, inputs, defaults, secrets, permissions, versions, labels, and expressions | | 79 extracted Markdown link/image targets and the HTML image target | Identical; no destination changes | | Nine front-matter blocks | Identical | | 75 normative modal tokens, in sequence | Identical; the complete replacement comparison also protects all other contract wording outside the released spans | | Other repository paths | No diff; workflows, implementation, tests, site configuration, assets, and design remain unchanged | The protected [fixed-secret/TestData section, lines 76-104](https://github.com/PSModule/Process-PSModule/blob/79bac09b581e80b27bae5dad5d87adffac0ff219/docs/content/guides/calling-the-workflow.md#L76-L104), including its heading, all seven old input names, mapping instructions, and complete adoption example, is byte-identical. Its source-LF region is 1,045 bytes with SHA-256 `96ac1034b74d2c76c8fc770d3f21a196b3d7cfd685210974d0a90d63bc61f54a` at both base and head. The existing CRLF worktree region is 1,074 bytes with SHA-256 `2a90ca000acc18720d4f281a8fb42e8b92206e9e968f9e70fc8dc3c39b37b05f` before and after. The entire calling-guide blob is unchanged. The coverage text retains this exact sample: ```yaml Test: CodeCoverage: PercentTarget: 80 ``` The [settings reference](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/docs/content/reference/settings.md#L53-L55) still defines the separate default as `0`. The [existing workflow mapping](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/.github/workflows/Get-CodeCoverage.yml#L27-L35) forwards that setting. The existing implementation [accepts coverage greater than or equal to its target](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/.github/actions/Get-PesterCodeCoverage/src/main.ps1#L157) and [fails only below target](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/.github/actions/Get-PesterCodeCoverage/src/main.ps1#L389-L396). The pre-edit experiment executes those extracted comparisons with target 80: 79.99 fails, 80 passes, and 80.01 passes. `At least 80%` clarifies this existing boundary; it does not change policy or behavior. The built-site comparison passes 12 explicit checks. It confirms the new prose, both reader roles, the existing development-framework anchor, the goal-setting and canonical-guidance destinations, both `labeled` sentences, the migration heading and all seven old input names, and the exact decoded coverage YAML. Code text is read without inserting whitespace between syntax-highlight spans. ### Existing checks and outcomes The existing Markdown configuration passes on all ten pages before and after the edits: markdownlint-cli2 0.24.0, markdownlint 0.42.0, 10 files, 0 issues. The existing codespell 2.4.2 CLI passes with the repository configuration. The existing Zensical 0.0.50 build passes before and after, reporting `No issues found`. The exact base-to-head whitespace check passes. These commands use the same ten-file set as the recorded runs: ```powershell $pages = @( 'README.md', 'docs\content\index.md', 'docs\content\get-started\index.md', 'docs\content\get-started\repository-setup.md', 'docs\content\get-started\your-first-release.md', 'docs\content\guides\calling-the-workflow.md', 'docs\content\guides\configuring-the-pipeline.md', 'docs\content\guides\github-app-authentication.md', 'docs\content\guides\structuring-your-module.md', 'docs\content\guides\versioning-and-releases.md' ) npx --no-install markdownlint-cli2 --config '.github\linters\.markdown-lint.yml' @pages codespell --config '.github\linters\.codespellrc' @pages Push-Location -LiteralPath 'docs' zensical build --clean Pop-Location git --no-pager diff --check 64ffb1d 79bac09 ``` No standalone link-check command exists in this repository. The existing site build reports no issues; separate exact link/heading comparisons and rendered destination checks confirm no link regression from these edits. This is not a new internet-wide link-validation claim. An initial `python -m codespell` invocation used the wrong entry point; the existing `codespell` CLI passes. No repository dependency is changed. Hosted snapshot at `2026-11-04T13:59:39Z`, for head `79bac09b581e80b27bae5dad5d87adffac0ff219`: | Hosted check | Result | | --- | --- | | [Docs Build](https://github.com/PSModule/Process-PSModule/actions/runs/41842493106/job/126617424058) | Success | | [Docs Lint](https://github.com/PSModule/Process-PSModule/actions/runs/41842493106/job/126617423266) | Success | | [Repository lint](https://github.com/PSModule/Process-PSModule/actions/runs/41842493216/job/126617425457) | Success | | [CodeQL](https://github.com/PSModule/Process-PSModule/runs/126617863969) | Success | | [Analyze (actions)](https://github.com/PSModule/Process-PSModule/actions/runs/41842487969/job/126617413004) | Success | | [Fresh Copilot review](#579 (review)) | Approved at the exact final head; no inline comments | | [Docs Publish](https://github.com/PSModule/Process-PSModule/actions/runs/41842493106/job/126617713362) | Skipped for the pull-request event | No hosted check or review remains pending at this snapshot. Earlier-head approval is not used as final-head evidence. The parent current-head content review also accepts `79bac09b581e80b27bae5dad5d87adffac0ff219` after independently checking the complete four-file diff and the protected structures across all ten pages. This content acceptance does not change draft or merge state. ### Standards, ownership, and scope alignment The fixed writing source is [MSXOrg/docs at `1b0d4893c8fefabe604d04393068a8ff6f848082`](https://github.com/MSXOrg/docs/tree/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs). The review covers Documentation Model; Natural Language; Writing Guide; Markdown; Documentation; the guide/reference templates; and the Task, PR, workflow, and commit formats. The official [STE overview](https://www.asd-ste100.org/about_STE.html), [FAQ](https://www.asd-ste100.org/STE_faq.html), and relevant Issue 9 rules/dictionary were consulted through the verified local manual. No manual material is republished. These edits apply STE writing practices; scans, counts, and lint do not establish full STE conformance. | Changed surface | Standards checked | Framework/source docs checked | Result | | --- | --- | --- | --- | | README opening | Pinned Natural Language, Writing Guide, Markdown, Documentation, Documentation Model | Existing README and site-index capabilities | Fixed in this PR | | Released site-index spans and spelling | Same pinned writing standards and artifact model | Source index and exact extended owner handback | Fixed in this PR | | Coverage-example description | Same pinned writing standards and guide format | Settings reference, workflow input mapping, source coverage comparison/failure boundary | Fixed in this PR | | Release-guide descriptive spelling | Pinned en-US and Markdown rules | Existing release paragraphs, examples, and settings references | Fixed in this PR | The source, issue scope, live owner heads, and intersecting paths are rechecked before each of the five commits and at final handoff. The source remains `64ffb1d87f86bd5d487891fdb140b78385a00531`. Active owner heads are unchanged: | Existing PR | Verified head | | --- | --- | | #524 | `0fb4234056b3bd4574c58cd4edd6dff2544d70f6` | | #525 | `03e24f359265b7a4106f8f71f769cba1ba12bf3c` | | #531 | `50f16425797ec67375d47262c8c79d3507fb2b21` | | #535 | `7204e1eb418f99848c396f7e3597152a70e362ff` | | #537 | `af22c475873b21b8afa5ba7ecb87cb2bf8efabd2` | | #548 | `eb3eb0cb8fb6f0b7822c79ad9b2781d17127dcd4` | | #549 | `663d87b9c11e7d5662a986f662e4f7499e816f55` | | #551 | `7a00cbb9cd72baddf14d990019cf5da3c9c3600e`; no intersection with the ten-page set | #565 through #570 retain disjoint paths and unchanged heads. No existing owner branch is awakened or edited. No new caller, release, compatibility, shipping, or enforcement contract is imported from a proposal. The issue-convergence search covers the open `documentation-writing-alignment` issues and the active owners intersecting this ten-page set. This diff resolves only #560. It does not resolve the reserved interface, source-contract, or TestData adoption work. No additional closing reference is added. No scoped wording decision remains. #578 retains the actual baseline/target, source-bound release-record, compatibility, and exact #535 / #537 owner decisions. This PR makes none of those decisions. The PR remains draft. No merge, ready transition, auto-merge, Agent merge, release-label, or publication action is performed. </details> <details> <summary>Related references</summary> - Resolves #560 - References #578; protected source-bound TestData adoption reconciliation remains separate and open. </details>
1 parent a40a9eb commit bc376d0

4 files changed

Lines changed: 10 additions & 10 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Process-PSModule
22

3-
Process-PSModule is the corner-stone of the PSModule framework — an end-to-end GitHub Actions workflow that builds, tests, versions, documents, and publishes PowerShell modules to the PowerShell Gallery.
3+
Process-PSModule is the core workflow of the PSModule framework. This end-to-end GitHub Actions workflow builds, tests, versions, documents, and publishes PowerShell modules to the PowerShell Gallery.
44

55
Documentation site generation is powered by Zensical. Repositories define site configuration in `zensical.toml`.
66

‎docs/content/guides/configuring-the-pipeline.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ This page shows the common changes. For the complete list of settings and their
1414

1515
## Example 1 - Defaults with Code Coverage target
1616

17-
This example runs all steps and will require that code coverage is 80% before passing.
17+
This example runs all steps and requires at least 80% code coverage to pass.
1818

1919
```yaml
2020
Test:

‎docs/content/guides/versioning-and-releases.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ the configured default branch.
1919

2020
Test and lint stages run before the publish gates, and publish is blocked when required checks fail.
2121

22-
An open labelled pull request can publish a prerelease. A closed pull request only cleans up its prereleases. When a
22+
An open labeled pull request can publish a prerelease. A closed pull request only cleans up its prereleases. When a
2323
pull request merges, the resulting push to the default branch resolves that pull request's labels and creates the
2424
stable release from the exact pushed commit.
2525

@@ -55,7 +55,7 @@ short-lived pull requests targeting `main`.
5555

5656
## Prereleases
5757

58-
A pull request labelled `Prerelease` publishes a prerelease version (for example `v1.2.3-pr.1.5`) that is installable
58+
A pull request labeled `Prerelease` publishes a prerelease version (for example `v1.2.3-pr.1.5`) that is installable
5959
but not promoted as latest. When that pull request is merged with a version label, the stable version is computed from
6060
the label and the current version on `main`.
6161

‎docs/content/index.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ default-branch push is the sole authority for a stable release. When that push i
1515
request, its labels and release notes supply the release metadata. See the
1616
[scenario matrix](reference/scenario-matrix.md) for the resulting job execution.
1717

18-
Everything is packaged into a single reusable workflow so that a module repository only needs a small caller workflow and one settings file. A user configures the behaviour by editing `.github/PSModule.yml`.
18+
Everything is packaged into a single reusable workflow so that a module repository only needs a small caller workflow and one settings file. A user configures the behavior by editing `.github/PSModule.yml`.
1919

2020
![Process diagram](media/Process-PSModule.png)
2121

@@ -77,16 +77,16 @@ The requirements and architecture behind the pipeline. Primarily for those maint
7777

7878
## A GitHub & PowerShell development framework
7979

80-
PSModule **infuses GitHub with PowerShell** and brings more to the PowerShell ecosystem by using the GitHub platform to its fullest extent.
81-
The framework is two things in one: a collection of reusable PowerShell modules, and a set of GitHub Actions workflows that automate the full PowerShell module (software) delivery lifecycle — the DevOps functionality that the ecosystem is missing.
80+
The PSModule framework has reusable PowerShell modules and GitHub Actions workflows.
81+
The workflows automate the PowerShell module delivery lifecycle.
8282

83-
We empower PowerShell-savvy developers to effortlessly transform their ideas into impactful solutions, automating the repetitive tasks so developers — whether consumers or contributors — can concentrate on coding without distractions.
83+
The framework automates repeated tasks so developers can write code for their PowerShell solutions. This applies to both consumers and contributors.
8484

85-
Where we are headed is tracked as [objectives and initiatives](https://msx.no/docs/Ways-of-Working/Goal-Setting/).
85+
See [objectives and initiatives](https://msx.no/docs/Ways-of-Working/Goal-Setting/) for the goal-setting model.
8686

8787
## Cross-org guidance
8888

89-
Cross-org standards and reusable solution documentation are now canonical in [MSXOrg/docs](https://msx.no/docs/):
89+
Cross-org standards and reusable solution documentation are canonical in [MSXOrg/docs](https://msx.no/docs/):
9090

9191
- [Coding Standards](https://msx.no/docs/Coding-Standards/)
9292
- [Capabilities](https://msx.no/docs/Capabilities/)

0 commit comments

Comments
 (0)