docs/RELEASING.md documents the forward release flow in detail — pack, dry-run publish, tag, the v0 major-tag move — but has no rollback procedure, and the information a rollback needs is not recorded anywhere.
Surfaced by the operator lens during the deep review of #119. Reported rather than fixed there, since it is pre-existing and unrelated to that diff.
Why this matters here specifically
The repository-backed Action is consumed as mbeacom/adrkit/packages/ci@v0, and v0 is a moving tag force-pushed by release.yml on each release. So:
- every consumer pinning
@v0 picks up a bad bundle immediately, with no opt-in step;
- reverting means force-pushing
v0 back to the prior release's target SHA;
- that prior SHA is not recorded anywhere. It has to be reconstructed from tag history at the moment you least want to be reconstructing things.
The failure mode this protects against is not hypothetical for this project. #119 fixed a bug where identical inputs produced different governing / activeProposals verdicts depending on the runner's ICU locale — exactly the kind of defect that ships green, reproduces on someone else's infrastructure and not yours, and is discovered from a downstream repo's confusing PR comment.
What would help
A short "Rollback: reverting the major Action tag" section covering:
- how to find the prior
v0 target (git rev-list -n 1 <previous-version-tag>), or better, having the release job record it in the run summary so it does not need deriving;
- the exact
git push --force-with-lease invocation, including whether the release job's auth pattern applies or a maintainer PAT is needed;
- whether consumers need to do anything — GitHub Actions' handling of a moved tag versus any cached ref;
- how this interacts with npm, where
@adrkit/* versions are immutable and the answer is a new patch rather than a revert. The two surfaces roll back differently and the doc should say so.
Worth checking whether scripts/update-action-tag.ts can emit the pre-move SHA into $GITHUB_STEP_SUMMARY, which would make (1) free.
Documentation-only; no code change implied beyond the optional summary line.
docs/RELEASING.mddocuments the forward release flow in detail — pack, dry-run publish, tag, thev0major-tag move — but has no rollback procedure, and the information a rollback needs is not recorded anywhere.Surfaced by the operator lens during the deep review of #119. Reported rather than fixed there, since it is pre-existing and unrelated to that diff.
Why this matters here specifically
The repository-backed Action is consumed as
mbeacom/adrkit/packages/ci@v0, andv0is a moving tag force-pushed byrelease.ymlon each release. So:@v0picks up a bad bundle immediately, with no opt-in step;v0back to the prior release's target SHA;The failure mode this protects against is not hypothetical for this project. #119 fixed a bug where identical inputs produced different
governing/activeProposalsverdicts depending on the runner's ICU locale — exactly the kind of defect that ships green, reproduces on someone else's infrastructure and not yours, and is discovered from a downstream repo's confusing PR comment.What would help
A short "Rollback: reverting the major Action tag" section covering:
v0target (git rev-list -n 1 <previous-version-tag>), or better, having the release job record it in the run summary so it does not need deriving;git push --force-with-leaseinvocation, including whether the release job's auth pattern applies or a maintainer PAT is needed;@adrkit/*versions are immutable and the answer is a new patch rather than a revert. The two surfaces roll back differently and the doc should say so.Worth checking whether
scripts/update-action-tag.tscan emit the pre-move SHA into$GITHUB_STEP_SUMMARY, which would make (1) free.Documentation-only; no code change implied beyond the optional summary line.