Repository navigation
[documentation-writing-alignment] Make entry pages and workflow guides evergreen #560
Description
Context and request
Readers need direct, evergreen entry-page and workflow-guide language. This delivery now owns only the settled prose regions released by the existing integration coordinator. It does not own whole proposal files or change a caller/release contract.
Exact source and region handback
The verified main source is 64ffb1d87f86bd5d487891fdb140b78385a00531. All listed blobs match that tree. Use content anchors, not incidental line positions, to retain the boundary.
| File and blob | Released wording |
|---|---|
README.md, c2d2257e3948184ebb8db36268f1c7490e0abcbc |
Opening corner-stone becomes cornerstone or an equivalent direct description with every existing capability retained. |
docs/content/index.md, 02cc155fc51c96deba28eaf9ae1f9e899baf2d97 |
Replace the We empower ... effortlessly paragraph with a direct description of the same automation; replace Where we are headed with a neutral objectives/initiatives link; remove now from are now canonical. Keep every destination and heading/anchor. The integration coordinator also releases the two adjacent statements at original lines 80-81 (infuses GitHub ... fullest extent and DevOps functionality ... missing) for a direct description of the same reusable PowerShell modules, GitHub Actions workflows, and automated delivery. Preserve the development-framework heading/anchor, all destinations, supported scope, and behavior. Add no shipping, exclusivity, completeness, or enforcement claim. No other region is released. |
docs/content/guides/configuring-the-pipeline.md, b77d4cdf2272ad592234076eec0a48afd692a926 |
Make the coverage-example description direct and present-tense. Preserve the exact 80% example and all YAML. |
docs/content/guides/versioning-and-releases.md, fe226002f077d1e0e7a01a01514d8112b3303317 |
Change labelled to labeled; preserve every release contract and example. |
The same narrowly linguistic en-US spelling corrections outside protected tokens/quotations are released in this Task's original ten-page set: the four files above; docs/content/get-started/{index,repository-setup,your-first-release}.md; and docs/content/guides/{calling-the-workflow,github-app-authentication,structuring-your-module}.md. No other paragraph rewrite is authorized by that spelling allowance.
Protected and split scope
The calling guide's Breaking change: fixed test secrets use TestData section, blob 8e18d7e18025b68a1abd318c115719607d3683c3 from its heading through the complete adoption example, remains unchanged. Its required actions need a verified source-bound release record and the exact #535 / #537 owner decision before relocation, deletion, or compatibility rewriting. That independent residual scope is #578, not a hold on the settled edits here.
Preserve all headings/anchors, links, literal names, public inputs/defaults, secrets, permissions, versions, YAML/commands, compatibility conditions, normative force, release decisions and site behavior. No new shipping/enforcement claim, functional change, site redesign or proposal-only content is permitted. Existing proposal branches remain untouched; do not wake/amend them or merge anything.
Evidence and acceptance criteria
The original index uses We empower PowerShell-savvy developers to effortlessly transform their ideas, Where we are headed, and are now canonical. The configuration example says it will require coverage. The release guide uses labelled. Compare these observed phrases with the pinned Natural Language, Writing Guide, Documentation Model and applicable guide/reference format.
- Released prose is direct, active, present-tense en-US; procedures remain imperative.
- The ten-page review records changed, no-change and protected results with concrete before/after evidence.
- Exact examples, technical tokens, link targets, headings and protected section text remain unchanged, except approved spelling in descriptive prose.
- All factual claims remain within the supported source contract; no requirement becomes proof of CI enforcement.
- One fresh-main focused draft PR uses small commits, opens after the first real change, and records relevant existing Markdown/link/site checks. No new dependency or prose-snapshot repository test is added.
Implementation plan
- Verify the owner handback, main source and exact source blobs; split the protected adoption scope into [documentation-writing-alignment] Verify source-bound TestData adoption guidance #578.
- Read the ten-page set and pinned writing sources; record expected changes and preservation checks before editing.
- Establish existing Markdown/link/site checks and protected-region/example/token baselines.
- Open the focused draft PR after the first real coherent commit: Entry pages and workflow examples use direct prose #579 at
93b95eb6935d43c3e350bcdd293e19c128dc7aa3. - Complete only the released index and guide changes in small follow-up commits.
- Clarify the coverage description as
at least 80%after the source-backed below/equal/above threshold check; preserve the exact YAML. - Recheck source/competing ownership before each commit; stop only for changed meaning, not incidental line movement.
- Verify wording, protected regions, examples, anchors and existing checks; record full acceptance/no-change evidence and keep the PR draft.
Delivery evidence
Draft PSModule/Process-PSModule#579 contains the released prose at head 79bac09b581e80b27bae5dad5d87adffac0ff219, based on main at 64ffb1d87f86bd5d487891fdb140b78385a00531. Five small commits are pushed. The PR opened after the first real commit. Its technical details record all ten changed/no-change/protected paths, immutable before/after citations, exact blob and protected-region comparisons, the source-backed at least 80% boundary experiment, existing check commands/outcomes, and the standards/ownership alignment.
All local checks pass. At the final hosted snapshot, Docs Build/Lint, repository lint, CodeQL, and Analyze pass; the fresh Copilot review approves this exact head with no inline comments. Docs Publish is skipped for the pull-request event. The parent independently accepts the final content. The PR remains draft with no auto-merge or labels. No lifecycle action changes.
No scoped wording decision remains. References #578, non-closing. Its source-bound adoption record and exact caller/release-owner decisions remain separate and open. This Task stays open until the reviewed draft is merged.
Activity
MariusStorhaug commentedon Nov 4, 2026
Recorded the exact owner-handback decision and source-verified proposal gates. A bounded amendment or settled-region release remains pending. No proposal branch was awakened or edited, and no functional or lifecycle decision changed.
MariusStorhaug commentedon Nov 4, 2026
The integration coordinator released the exact settled prose regions on fresh main-based branches. The current body records source blobs, allowed spelling, protected contracts, and the split TestData adoption leaf #578. This supersedes the blanket ownership hold, not the protected release-record decision. No proposal branch or lifecycle setting changed.
MariusStorhaug commentedon Nov 4, 2026
Pre-edit evidence for the released prose scope:
The worktree and live
mainboth resolve to64ffb1d87f86bd5d487891fdb140b78385a00531. All five supplied blob IDs match. All ten pages have been read in full. The writing source isMSXOrg/docs@1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs, not a moving revision.corner-stoneparagraphProcess-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.behaviourbehaviorinfuses GitHub ... fullest extentandDevOps functionality ... missingThe PSModule framework has reusable PowerShell modules and GitHub Actions workflows.followed byThe workflows automate the PowerShell module delivery lifecycle.We empower ... effortlessly ... without distractionsThe framework automates repeated tasks so developers can write code for their PowerShell solutions. This applies to both consumers and contributors.Where we are headed ...See [objectives and initiatives](https://msx.no/docs/Ways-of-Working/Goal-Setting/) for the goal-setting model.are now canonicalare canonicalwill require that code coverage is 80% before passingThis example runs all steps and requires 80% code coverage to pass.labelledtwicelabeledtwiceThe one-off session-local comparison records the original seven expected wording results as absent before editing, with eight source occurrences. The explicit two-statement extension adds one expected result, for eight wording results and nine source occurrences. It permits only these exact replacements. It also records 25 complete fenced blocks, 66 headings, 234 inline-code spans, 79 Markdown link/image targets, the HTML image target, front matter, and normative modal sequences. No repository test, inventory, dependency, or enforcement tool is added.
The entire calling guide stays unchanged. Its protected migration section, from the
Breaking change: fixed test secrets use TestDataheading through the complete adoption example, has 1,074 worktree bytes and SHA-2562a90ca000acc18720d4f281a8fb42e8b92206e9e968f9e70fc8dc3c39b37b05fwith the checkout's existing CRLF line endings. Its source file blob remains8e18d7e18025b68a1abd318c115719607d3683c3.The coverage wording is supported by the unchanged settings reference, the
Get-CodeCoverageinput mapping, and the comparison/failure path inGet-PesterCodeCoverage/src/main.ps1. This is evidence for the existing example, not a new CI-enforcement claim.Baseline checks:
npx --no-install markdownlint-cli2 --config .github\linters\.markdown-lint.yml <ten named files>; 10 files, 0 issues.docs:zensical build --clean;No issues found, Zensical 0.0.50.python -m codespellinvocation fails. The check uses thecodespellCLI entry point from a session-local environment with the existing repository configuration.Live ownership is recorded for #524, #525, #531, #535, #537, #548, #549, and #551. The six writing PRs #565 through #570 have no path intersection with this ten-page set. Before each commit, the live source, issue scope, owner heads, and scoped paths are compared again. A changed owner result requires a meaning check, not an automatic rejection for line movement.
References #578. The protected adoption record and compatibility decision remain outside this PR. No existing proposal branch is amended or awakened.
MariusStorhaug commentedon Nov 4, 2026
The README opening is committed and pushed. #579 is open in draft after that first real change. The released index and guide edits remain in progress. The existing codespell CLI also passes on the unchanged ten-page baseline with the repository configuration; the earlier module-form invocation was not the CLI entry point.
MariusStorhaug commentedon Nov 4, 2026
The released site-index edits are committed and pushed in #579 at 05d24e1. This includes the explicit two-statement handback extension recorded in the issue body. The comparison confirms that all other index text, every heading and destination, and all protected content remain unchanged. The coverage description and release-guide spelling remain in progress.
MariusStorhaug commentedon Nov 4, 2026
Before the review clarification: #579 at 13e93f1 says
requires 80% code coverage. Parent review requestsrequires at least 80% code coverageto avoid an exact-equality reading. The unchanged main source at 64ffb1d uses$coveragePercent -ge $coveragePercentTargetat.github/actions/Get-PesterCodeCoverage/src/main.ps1:157and rejects only$coveragePercent -lt $coveragePercentTargetat line 390. A one-off experiment executes those extracted comparisons with target 80: 79.99 fails, 80 passes, and 80.01 passes. The expected clarification is absent before editing, and its exact-wording comparison fails as expected. The next edit changes only that description;PercentTarget: 80, all other YAML, and every protected region remain unchanged. No policy, threshold, behavior, or compatibility decision changes.MariusStorhaug commentedon Nov 4, 2026
Final acceptance evidence
The released prose is delivered in draft PSModule/Process-PSModule#579. The exact pushed head is
79bac09b581e80b27bae5dad5d87adffac0ff219, onentry-guidance-prose. Its exact base ismainat64ffb1d87f86bd5d487891fdb140b78385a00531. The diff contains four files, 10 insertions, and 10 deletions.The draft opened after the first real commit,
93b95eb6935d43c3e350bcdd293e19c128dc7aa3. Four small follow-up commits are pushed, including the source-backedat least 80%clarification. No source change remains pending.Complete ten-page disposition
All ten pages were read in full before editing. The spelling allowance did not expand paragraph-rewrite permission.
README.mddocs/content/index.mdbehaviourat line 18; the explicitly released adjacent statements at lines 80-81; the task-automation paragraph at line 83; the goal-setting link sentence at line 85; andare now canonicalat line 89.docs/content/guides/configuring-the-pipeline.mdThis example runs all steps and requires at least 80% code coverage to pass.The exact 80% YAML remains unchanged.docs/content/guides/versioning-and-releases.mdlabelledtolabeledat lines 22 and 58. All release conditions and examples remain unchanged.docs/content/get-started/index.md72cc182b8e790c4b5420277d69a61de934a02791at base and head.docs/content/get-started/repository-setup.md790cf5eafb2946cad7c61398e7f80c7fcf6cc8a5at base and head.docs/content/get-started/your-first-release.mde8b00fb1c220108790517d151dc59b707d895928at base and head.docs/content/guides/calling-the-workflow.md8e18d7e18025b68a1abd318c115719607d3683c3at base and head.docs/content/guides/github-app-authentication.mdcf35933a019eaf977a8ce39ad940ab809edfe9b5at base and head.docs/content/guides/structuring-your-module.mdc4f36cf327b9e5f045a02b7d05bbb54e7bb39334at base and head.The PR's technical details contain immutable before/after source citations for every changed region, all ten page links, and full base/head blob identities. The original pre-edit evidence records the exact expectations before the first source edit. The threshold evidence records the review clarification before its edit.
The actual source comparison accepts coverage at or above its target and rejects only coverage below it. The one-off experiment executes those extracted comparisons with target 80: 79.99 fails, 80 passes, and 80.01 passes. This supports
at least 80%without changing the threshold, policy, or behavior.Exact preservation results
All eight declared replacement expectations pass at the final head. The comparison rejects any other text change. It confirms identical 25 complete fences, 66 headings, 234 inline-code spans, 79 extracted Markdown link/image targets, the HTML image target, nine front-matter blocks, and 75 normative modal tokens in sequence.
All literal names, public inputs/defaults, secrets, permissions, versions, commands/YAML, compatibility conditions, release decisions, and normative force remain unchanged. The source settings default remains
0; the example remains exactlyPercentTarget: 80. The development-framework heading/anchor and every destination remain unchanged. Twelve rendered-site checks also pass, including the exact decoded YAML, both reader roles, the goal-setting and canonical-guidance destinations, bothlabeledsentences, and the migration heading/input names.The protected migration region from its heading through the complete adoption example, lines 76-104, is identical at base and head:
96ac1034b74d2c76c8fc770d3f21a196b3d7cfd685210974d0a90d63bc61f54a2a90ca000acc18720d4f281a8fb42e8b92206e9e968f9e70fc8dc3c39b37b05fNo workflow, implementation, repository test, dependency, validation tool, site configuration, design, asset, or other path changes. One-off evidence stays in the session. No manual material is republished, and no full STE-conformance claim is made.
Existing checks and review
The PR records the exact ten-file argument array and reproducible commands.
npx --no-install markdownlint-cli2 --config '.github\linters\.markdown-lint.yml' @pagescodespell --config '.github\linters\.codespellrc' @pageszensical build --clean, fromdocsNo issues found; Zensical 0.0.50git --no-pager diff --check 64ffb1d87f86bd5d487891fdb140b78385a00531 79bac09b581e80b27bae5dad5d87adffac0ff219No standalone repository link-check command exists. The existing site build, exact link/heading comparisons, and rendered destination checks supply separate regression evidence. This does not claim internet-wide link validation. The initial
python -m codespellinvocation used the wrong entry point; the existing CLI passes.At
2026-11-04T13:59:39Z, all final-head hosted checks are complete:79bac09b581e80b27bae5dad5d87adffac0ff219, with no inline comments.The parent current-head content review also accepts this exact head after an independent four-file diff review and ten-page protection comparison. This acceptance does not change the draft state.
Ownership and remaining decisions
Live main, the released issue scope, owner heads, and intersecting paths are rechecked before each of the five commits and at final handoff. The source and owner heads remain unchanged. #524, #525, #531, #535, #537, #548, and #549 retain their contracts and branches. #551 has no ten-page intersection. #565 through #570 retain disjoint paths and unchanged heads. No existing owner branch is awakened or amended.
The scoped issue-convergence search finds no additional issue fully resolved by this diff. Only #560 has a closing reference in the PR.
No scoped wording decision remains. References #578, non-closing. Its actual baseline/target, source-bound adoption record, compatibility decision, and exact #535 / #537 owner decision remain separate and open. This PR does not choose them.
The PR remains draft. No merge, ready transition, auto-merge, Agent merge, release-label, or publication action is performed. This Task stays open until the reviewed draft is merged.