ci: check the report action's tag against the workspace version - #412
Conversation
The `report@vX.Y.Z` action tag lives in three hand-maintained files, and the workspace version is a fourth copy of the same number. Releases bumped two of the three twice — 0.11.0 and 0.11.1 both left the action's own README at v0.10.1 — and nothing checked it, which is the class `check-candidate-statement.sh` already exists for. `.github/actions/report/README.md` is at v0.11.1 now; `docs/RELEASING.md` step 1 names all three files and the gate; `check-report-pin.sh` compares every `actions/report@vX.Y.Z` ref in the three files against `workspace.package.version` — stale refs, a listed file with no ref, and one stale ref among two all fail it. It runs in CI's `docs` job beside the candidate check, and `tools/report-pin-gate-selftest/run.sh` proves it can fail in the `gates-listed` job beside the link gate's selftest. CONTRIBUTING §1 lists both. Closes vyncint#386 Signed-off-by: whiteye <62688683+maskjelly@users.noreply.github.com>
vyncint
left a comment
There was a problem hiding this comment.
Thanks! Merging as is.
I hand-edited the pin in each of the three real sites in turn and the gate went red on every one, naming the file and both versions:
::error::.github/actions/report/README.md pins `report@v0.10.1` but the workspace version is 0.11.1
Two things you did that the issue did not ask for and that make this gate worth having.
The absent.md fixture — a listed file that has lost its pin — covers a failure the issue never named, and it is the one that would let a silent deletion through. A gate that only checks the pins it finds is a gate that passes when someone deletes the line.
Pinning REPORT_PIN_VERSION to 9.9.9 in the fixtures keeps them from going stale at every release, while the last assertion still runs the real three files against the real workspace version. That is the difference between a selftest and a second thing to maintain.
You were also right to exclude the report@v0.11.1 in CHANGELOG.md: it is historical prose under a released heading and must not move. Requiring the actions/ prefix is the right way to say that.
One thing for a later PR, not this one: check-ci-gates-listed.sh extracts only - run: cargo … lines, so its green says nothing about either of your two new steps. You listed both in CONTRIBUTING §1 by hand and correctly, but nothing enforces it — that is #383, already open.
Closes #386.
What changed. The
report@vX.Y.Ztag is pinned in three hand-maintained files, and the workspace version is a fourth copy of the same number. The action's own README was still atv0.10.1— releases bumped two of the three and missed it twice. This PR:.github/actions/report/README.mdtov0.11.1, so all three refs matchworkspace.package.version.docs/RELEASING.mdstep 1, beside the flag gate.check-report-pin.sh— the "better still" from the issue — in CI'sdocsjob besidecheck-candidate-statement.sh, andtools/report-pin-gate-selftest/run.shingates-listedbeside the link gate's selftest, withCONTRIBUTING§1 listing both.What the gate checks. Every
actions/report@vX.Y.Zref in the three files must equalworkspace.package.version. It fails on a stale ref, on one stale ref among several, and on a listed file whose ref is gone entirely (a copy that quietly disappeared is drift too). The file list is a single default in the script, so the next file to carry the pin is a one-line addition.REPORT_PIN_VERSIONexists only so the selftest can pin its fixtures to a version that does not move every release; CI never sets it, and the script header says so.How it is proven. The selftest asserts the four failure shapes (matching passes; stale fails; absent fails; one stale among two fails) and — the assertion that keeps it honest — the repository's own three files against the real version. All five green locally, as are
check-candidate-statement.sh,check-readme-links.shandcheck-ci-gates-listed.sh.Not done, deliberately. No CHANGELOG entry: no user-facing change, matching the link-gate precedent (#353). And the gate checks the three current files, not every
report@string in the repository — a repo-wide grep would flag the historical pins CHANGELOG entries quote, which are correct as history. If you would rather it scan wider with an exclusion list, that is an easy change.One note on ordering. The
CONTRIBUTING.md§1 lines this adds sit in the same block as the link-gate invocation line that #407 touches; whichever of the two lands second, I will rebase it.