Repository navigation
Commit 96a4f16
authored
Reusable action readers get direct behavior descriptions (#569)
Reusable action readers get direct descriptions of test results,
coverage thresholds, and setup guidance. Three READMEs use present-tense
statements and name the actor for each result. The prose edits require
no caller changes.
<!-- ANNOUNCEMENT STOP -->
## Changed: Reusable action guidance names each actor
The Pester-result reference states what the action collects, writes, and
treats as a failure. The coverage reference states how the action uses
the target and summary-selection input. The installer reference uses
neutral setup prose instead of promotion. The workflow recommendation
remains advisory.
Input settings, output and artifact names, commands, complete examples,
version references, and failure semantics stay unchanged. Four short
site-action references need no edit. Existing source-contract gaps
remain explicit exceptions in the open follow-up; this PR does not
certify or repair them.
<details>
<summary>Technical details</summary>
### Delivery and immutable scope
This draft opens after the first coherent commit. It stays draft; merge,
auto-merge, and Agent merge are excluded.
| Identity | Value |
| --- | --- |
| Repository | `PSModule/Process-PSModule` |
| Scoped PR base and evidence snapshot |
`64ffb1d87f86bd5d487891fdb140b78385a00531` |
| Pushed final head | `2742b3da509fbdd67caf5c5c5d2c19a8959dd899` |
| First commit | `11e54fa38bb4a2aae57140ed6c55efecfa4f8726` -
test-result prose |
| Second commit | `cb48ff8308ddb46d98eb3527f0e4dbc4289b705c` - coverage
prose |
| Third commit | `2742b3da509fbdd67caf5c5c5d2c19a8959dd899` - neutral
installer prose |
| Comparison | `git diff 64ffb1d
2742b3d` |
The remote branch and GitHub report the same final head. The worktree is
clean. This is scoped prose-only evidence, not a release-bound coverage
record. Release labels, publication behavior, and configuration remain
unchanged.
### Reviewed paths
All paths below are under `.github/actions/`. Every README has a full
manual review against its local `action.yml` and entry script. The
coverage helper, site helper scripts, Pester caller workflows, and
[pinned GitHub-Script
bootstrap](https://github.com/PSModule/GitHub-Script/tree/8083ec1f733f00357ee4d0db0c6056686e483bc0)
supply related evidence.
| README | Writing result | Factual result |
| --- | --- | --- |
| `Get-PesterTestResults/README.md` | Changed: direct collection, log,
failure, and caller prose | `Latest` default and standalone example
remain exceptions, not accuracy passes |
| `Get-PesterCodeCoverage/README.md` | Changed: direct results,
threshold, and summary-control prose | Download prerequisite, output
route, `Latest` default, and standalone example remain exceptions, not
accuracy passes |
| `Install-PSModule/README.md` | Changed: neutral introduction,
recommendation, output statement, and example lead-in |
`Helpers`/`PSModule`, copied version, and both examples remain
exceptions, not accuracy passes |
| `Build-ZensicalSite/README.md` | Reviewed, no change | Metadata/source
agree with the documented output path and required input |
| `Inject-SiteScripts/README.md` | Reviewed, no change | Metadata/source
agree with the injector path and required/default inputs |
| `Install-Zensical/README.md` | Reviewed, no change | Source installs
the CLI with `pip install zensical`; metadata defines no inputs |
| `Structure-Site/README.md` | Reviewed, no change | Metadata/source
agree with content/config output and required/optional inputs |
All four no-change files retain their baseline Git blob identities. No
new reference layout or template scaffolding is added.
### Exact before/after evidence
| Surface | Before | After |
| --- | --- | --- |
| Test-result introduction | `A GitHub Action that gathers Pester test
results for the PSModule process by analyzing test artifacts from the
workflow run.` | `This GitHub Action collects Pester test results from
workflow artifacts for the PSModule process.` |
| Test-result work and result | `It validates test execution and
results, providing a summary and failing if any tests are unsuccessful.`
| `The action examines test execution and results. It writes a summary
and fails if tests do not pass.` |
| Advice in all three changed READMEs | `It is recommended to use the
[Process-PSModule
workflow](https://github.com/PSModule/Process-PSModule) to automate the
whole process of managing the PowerShell module.` | `For the recommended
setup, use the [Process-PSModule
workflow](https://github.com/PSModule/Process-PSModule) to automate
PowerShell module management.` |
| Test-result logs | `Detailed results are logged in the workflow run's
output.` | `The action writes detailed results to the workflow run log.`
|
| Test-result failure | `If any tests fail or errors occur, the action
exits with a non-zero code, marking the workflow step as failed.` | `If
tests fail or errors occur, the action exits with a nonzero code. GitHub
Actions marks the workflow step as failed.` |
| Coverage threshold | `Fails the workflow if coverage falls below
specified targets.` | `If coverage is below the specified target, the
action fails the workflow.` |
| Coverage troubleshooting | `Enable debugging by setting inputs:` | `To
get debug and verbose output, set these inputs:` |
| Installer example lead-in | `Here's a complete workflow example
demonstrating how to use the Install-PSModule action:` | `This example
shows the action in a workflow:` |
The test-result behavior matches [artifact
collection](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/.github/actions/Get-PesterTestResults/src/main.ps1#L24-L25),
[result/failure
evaluation](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/.github/actions/Get-PesterTestResults/src/main.ps1#L136-L195),
and [summary/exit
handling](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/.github/actions/Get-PesterTestResults/src/main.ps1#L201-L240).
Coverage target selection matches [lines
123-131](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/.github/actions/Get-PesterCodeCoverage/src/main.ps1#L123-L131);
failure below target matches [lines
389-397](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/.github/actions/Get-PesterCodeCoverage/src/main.ps1#L389-L397).
### Retained factual exceptions
#572 is the open owning-repository Task for
each exception below. Existing action-folder and action-repository
issues were checked before it was filed; they do not own these repairs.
| Exception | Evidence and preserved boundary |
| --- | --- |
| Installer module and copied version | The README names `Helpers` and a
latest copy; [local
source](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/.github/actions/Install-PSModule/src/main.ps1#L8-L17)
installs bundled `PSModule` at `999.0.0`. All three behavior bullets and
both fenced examples remain unchanged. |
| Coverage CLI prerequisite | The README requires `gh run download`;
[local
source](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/.github/actions/Get-PesterCodeCoverage/src/main.ps1#L34-L35)
delegates to PowerShell artifact functions. A transitive CLI requirement
is not established by this local script. The exact requirement and
command remain unchanged. |
| Coverage output route | [Local
metadata](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/.github/actions/Get-PesterCodeCoverage/action.yml#L38-L59)
refers to a step with no `id`; [pinned GitHub-Script
metadata](https://github.com/PSModule/GitHub-Script/blob/8083ec1f733f00357ee4d0db0c6056686e483bc0/action.yml#L73-L76)
exposes only `result`. [The
script](https://github.com/PSModule/Process-PSModule/blob/64ffb1d87f86bd5d487891fdb140b78385a00531/.github/actions/Get-PesterCodeCoverage/src/main.ps1#L224-L226)
writes the value to the inner step's `GITHUB_OUTPUT`. The outer output
is not established; neither metadata nor the documented output is
changed here. |
| Pester `Version` defaults | Both README tables retain `Latest`. [The
pinned
bootstrap](https://github.com/PSModule/GitHub-Script/blob/8083ec1f733f00357ee4d0db0c6056686e483bc0/src/init.ps1#L21-L68)
can reuse an installed GitHub module when no version is set. An
unconditional latest-version guarantee is not established for that
environment. |
| Coverage standalone/local example | `Get-PesterCodeCoverage/README.md`
calls `PSModule/Get-PesterCodeCoverage@v1`; the framework caller uses
`./_wf/.github/actions/Get-PesterCodeCoverage`. The targets differ. The
exact example remains unchanged; source equivalence is not established.
|
| Test-result standalone/local example |
`Get-PesterTestResults/README.md` calls
`PSModule/Get-PesterTestResults@v1`; the framework caller uses
`./_wf/.github/actions/Get-PesterTestResults`. The targets differ. The
exact example remains unchanged; source equivalence is not established.
|
| Installer standalone/local examples | Both examples call
`PSModule/Install-PSModule@v1`; the local composite runs its bundled
script. The full example queries `Helpers`, while local source installs
`PSModule`. Both examples remain unchanged; source equivalence is not
established. |
These are not acceptance passes for factual accuracy. No live workflow
reproduction is claimed for the output-route defect. No contract,
runtime, lifecycle metadata, version policy, or example-target repair is
included in this writing PR.
### Validation
The existing Markdown configuration runs on all seven owned files:
```powershell
$readmes = @(
'.github\actions\Build-ZensicalSite\README.md',
'.github\actions\Get-PesterCodeCoverage\README.md',
'.github\actions\Get-PesterTestResults\README.md',
'.github\actions\Inject-SiteScripts\README.md',
'.github\actions\Install-PSModule\README.md',
'.github\actions\Install-Zensical\README.md',
'.github\actions\Structure-Site\README.md'
)
npx --no-install markdownlint-cli2 --config .github\linters\.markdown-lint.yml @readmes
git diff --check 64ffb1d HEAD
```
Both commands exit `0`. Markdownlint checks seven files and reports zero
issues. It uses `markdownlint-cli2 v0.24.0` and `markdownlint v0.42.0`.
The same check passes before edits and on each changed file. No
dependency is installed.
Native PowerShell comparisons against `git show <base>:<path>` verify
all 11 complete fenced examples, including the indented
`StepSummary_Mode` YAML block. They match after CRLF/LF normalization.
The final fence matcher includes up to three leading spaces and matching
closing indentation; this corrects the earlier column-zero-only count.
The comparisons also verify unchanged headings apart from case, all six
prose-link URLs, inline code identifiers, input name/required/default
cells, the three conflicting installer bullets, and the deferred CLI
requirement. The four no-change READMEs have identical Git blob hashes.
Nine targeted wording checks fail on the original prose and pass after
the edit. These preservation passes do not certify the retained contract
claims.
No dedicated documentation link checker exists in this checkout.
Markdownlint checks same-file fragments. Both unchanged unique
prose-link targets return HTTP `200` from `Invoke-WebRequest -Method
Head`. Heading capitalization changes preserve their slugs. No
cross-owner anchor or link repair is needed.
A native Copilot review was explicitly requested. Review `5768356776` is
`APPROVED` at the final head and has no inline comments. The review does
not resolve or override the factual exceptions. At final inspection, all
reported GitHub checks are complete with `SUCCESS` or `SKIPPED`; none
reports failure. This includes the repository linter and both
default/manifest workflow test runs.
### Standards and framework alignment
The fixed writing source is
`MSXOrg/docs@1b0d4893c8fefabe604d04393068a8ff6f848082`, not a moving
branch. The review reads [Documentation
Model](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Ways-of-Working/Documentation-Model.md),
[Natural
Language](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Natural-Language.md),
[Writing
Guide](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Writing-Guide.md),
[Markdown](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Markdown.md),
[Documentation](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Coding-Standards/Documentation.md),
and the [reference/guide
templates](https://github.com/MSXOrg/docs/blob/1b0d4893c8fefabe604d04393068a8ff6f848082/src/docs/Ways-of-Working/Spec-Driven-Development-Templates.md).
Pinned Task, PR Format, and commit conventions govern the delivery
evidence.
The review also reads the official [STE
description](https://www.asd-ste100.org/about_STE.html),
[FAQ](https://www.asd-ste100.org/STE_faq.html), and relevant rules and
dictionary entries in [Issue
9](https://doi.org/10.5281/zenodo.23666006). The local read-only PDF
matches the publisher's MD5, `9c720341c350ed77943b2c73d01c716f`. All
required sources are available. No manual content is republished. No
automated scan proves full STE conformance.
| Changed surface | Standards checked | Framework docs checked | Result
|
| --- | --- | --- | --- |
| `.github/actions/Get-PesterTestResults/README.md` | Pinned writing,
Markdown, Documentation Model, reference/guide format; relevant STE
rules/dictionary | Local action metadata, entry script, Pester caller,
pinned GitHub-Script bootstrap | Writing fixed in this PR; factual
exceptions owned by #572 |
| `.github/actions/Get-PesterCodeCoverage/README.md` | Same pinned
writing and reference standards | Local action metadata, entry/helper
scripts, Pester caller, pinned GitHub-Script output/bootstrap | Writing
fixed in this PR; factual exceptions owned by
#572 |
| `.github/actions/Install-PSModule/README.md` | Same pinned writing and
reference standards | Local action metadata and bundled-module
installation source | Neutral writing fixed in this PR; factual
exceptions owned by #572 |
### Plan, ownership, and exclusions
The delivery issue's test-first plan records expected wording properties
and baseline failures before edits, full source review, small commits,
the early draft, final preservation checks, and retained factual
exceptions. The writing steps are complete. The open follow-up owns the
contract work.
Open PR ownership is checked before each commit. No other PR changes an
assigned README. Direct inspection confirms that
#551 changes no README or action metadata. The
scoped issue-convergence sweep checks open README/action issues, the
seven action names, the documentation-writing-alignment family, and
#442 and #360. Only
#557 is satisfied by this writing diff. The
follow-up and sibling issues remain open.
Excluded paths are all other README files;
`.github/actions/**/action.yml`; action runtime source and native help
under `.github/actions/**/src/**`; tests; `docs/**`;
`.github/plugin/**`; `.github/workflows/**`; site configuration and
generated output. Publish, Release, Resolve, and Cleanup action docs
belong to existing release/recovery PRs and are excluded in full. No new
linter, dependency, generated file, site design, or framework behavior
is added.
</details>
<details>
<summary>Related references</summary>
- Resolves #557
- Followed by #572
</details>1 parent 800ad2a commit 96a4f16
3 files changed
Lines changed: 65 additions & 65 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | 2 | | |
3 | | - | |
4 | | - | |
| 3 | + | |
| 4 | + | |
5 | 5 | | |
6 | | - | |
7 | | - | |
| 6 | + | |
| 7 | + | |
8 | 8 | | |
9 | 9 | | |
10 | 10 | | |
11 | | - | |
12 | | - | |
13 | | - | |
14 | | - | |
15 | | - | |
16 | | - | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
17 | 17 | | |
18 | 18 | | |
19 | 19 | | |
| |||
26 | 26 | | |
27 | 27 | | |
28 | 28 | | |
29 | | - | |
| 29 | + | |
30 | 30 | | |
31 | 31 | | |
32 | | - | |
| 32 | + | |
33 | 33 | | |
34 | 34 | | |
35 | 35 | | |
| |||
43 | 43 | | |
44 | 44 | | |
45 | 45 | | |
46 | | - | |
| 46 | + | |
47 | 47 | | |
48 | | - | |
| 48 | + | |
49 | 49 | | |
50 | | - | |
| 50 | + | |
51 | 51 | | |
52 | | - | |
53 | | - | |
54 | | - | |
55 | | - | |
| 52 | + | |
| 53 | + | |
| 54 | + | |
| 55 | + | |
56 | 56 | | |
57 | | - | |
58 | | - | |
59 | | - | |
60 | | - | |
61 | | - | |
| 57 | + | |
| 58 | + | |
| 59 | + | |
| 60 | + | |
| 61 | + | |
62 | 62 | | |
63 | 63 | | |
64 | 64 | | |
| |||
77 | 77 | | |
78 | 78 | | |
79 | 79 | | |
80 | | - | |
| 80 | + | |
81 | 81 | | |
82 | | - | |
83 | | - | |
| 82 | + | |
| 83 | + | |
84 | 84 | | |
85 | 85 | | |
86 | 86 | | |
| |||
89 | 89 | | |
90 | 90 | | |
91 | 91 | | |
92 | | - | |
93 | | - | |
94 | | - | |
95 | | - | |
| 92 | + | |
| 93 | + | |
| 94 | + | |
| 95 | + | |
96 | 96 | | |
97 | | - | |
98 | | - | |
99 | | - | |
100 | | - | |
| 97 | + | |
| 98 | + | |
| 99 | + | |
| 100 | + | |
| 101 | + | |
101 | 102 | | |
102 | | - | |
103 | | - | |
| 103 | + | |
| 104 | + | |
104 | 105 | | |
105 | 106 | | |
106 | 107 | | |
| |||
114 | 115 | | |
115 | 116 | | |
116 | 117 | | |
117 | | - | |
| 118 | + | |
118 | 119 | | |
119 | 120 | | |
120 | 121 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | 2 | | |
3 | | - | |
4 | | - | |
| 3 | + | |
| 4 | + | |
5 | 5 | | |
6 | | - | |
7 | | - | |
| 6 | + | |
| 7 | + | |
8 | 8 | | |
9 | 9 | | |
10 | 10 | | |
11 | | - | |
12 | | - | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
13 | 14 | | |
14 | 15 | | |
15 | 16 | | |
16 | 17 | | |
17 | 18 | | |
18 | | - | |
19 | | - | |
20 | | - | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
21 | 22 | | |
22 | 23 | | |
23 | 24 | | |
24 | | - | |
25 | | - | |
| 25 | + | |
| 26 | + | |
26 | 27 | | |
27 | 28 | | |
28 | 29 | | |
29 | 30 | | |
30 | | - | |
| 31 | + | |
| 32 | + | |
31 | 33 | | |
32 | 34 | | |
33 | 35 | | |
34 | | - | |
| 36 | + | |
35 | 37 | | |
36 | | - | |
37 | | - | |
| 38 | + | |
| 39 | + | |
38 | 40 | | |
39 | 41 | | |
40 | 42 | | |
| |||
48 | 50 | | |
49 | 51 | | |
50 | 52 | | |
51 | | - | |
| 53 | + | |
52 | 54 | | |
53 | 55 | | |
54 | | - | |
55 | | - | |
56 | | - | |
| 56 | + | |
| 57 | + | |
| 58 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | 2 | | |
3 | | - | |
4 | | - | |
| 3 | + | |
5 | 4 | | |
6 | | - | |
7 | | - | |
| 5 | + | |
| 6 | + | |
8 | 7 | | |
9 | 8 | | |
10 | 9 | | |
11 | 10 | | |
12 | 11 | | |
13 | 12 | | |
14 | 13 | | |
15 | | - | |
16 | | - | |
17 | 14 | | |
18 | 15 | | |
19 | 16 | | |
| |||
31 | 28 | | |
32 | 29 | | |
33 | 30 | | |
34 | | - | |
| 31 | + | |
35 | 32 | | |
36 | 33 | | |
37 | 34 | | |
38 | | - | |
| 35 | + | |
39 | 36 | | |
40 | 37 | | |
41 | 38 | | |
| |||
0 commit comments