docs(readme): say who moves the v1 tag, when, and what it promises

The Versioning section named the moving-major-tag model but not the release
step that model implies. This is the first change where that gap has a
consequence: `v1` and `origin/main` are the same commit today, so merging
the eviction fix is the first thing that makes them diverge — at which point
the fix is on `main` and every consumer is still fetching the old scripts.

Records what was previously only implicit: that merging ships nothing, that
re-pointing `v1` is a deliberate post-merge action because it changes what
another repository's CI runs next, the exact commands and the check that it
took, what a consumer is promised by pinning `@v1` and what forces a `v2`,
and who is actually downstream. Also states why the moving pointer is the
right model here rather than immutable release tags, since "safer in
general" is the obvious objection and it deserves an answer.

Docs only; no script or action definition is touched.
This commit is contained in:
2026-08-23 23:13:25 -05:00
parent 88ab063b64
commit c6a3fa6d97
+39
View File
@@ -305,6 +305,45 @@ Pin `@v1`. It is a moving major tag: fixes and backward-compatible inputs move
it forward, and anything that would break an existing consumer gets `v2`
instead. Pin a commit SHA if you want a frozen version.
The alternative is immutable release tags — `v1.0.1`, `v1.0.2`, … — with every
consumer edited to point at the new one per fix. That is the safer model in
general and the wrong one here. What it buys is the ability to hold one
consumer back on a known-good version; what it costs is a PR in every consumer
repo per fix, and its real failure mode with two consumers and one operator is
that the second one is simply never updated and quietly runs a version nobody
is testing. The moving pointer makes a release one action with one blast
radius, which is the thing worth being deliberate about. Anyone who wants the
immutable behaviour already has it, by pinning a SHA.
**What `@v1` promises** is that whatever it points at works with the inputs
documented above, spelled as they are documented. A change that renames or
removes an input, changes a default in a way that changes behaviour, or
requires something new of the consuming workflow — another `container.volumes`
entry, another permission — is a `v2`, not a `v1` move. Everything else moves
`v1`: correctness fixes, new optional inputs, and anything internal to
`scripts/`.
**Moving the tag is a release step, and it is the operator's.** Merging to
`main` ships nothing to anybody. `v1` is a lightweight tag and does not follow
a branch, so until it is re-pointed every consumer keeps fetching the commit it
already named, whatever `main` now says. The gap is deliberate: re-pointing
`v1` changes what another repository's CI executes on its next run, so it is a
decision taken once, knowingly, after the merge — never something a merge does
by itself.
```bash
git fetch origin
git tag -f v1 origin/main
git push -f origin v1
git ls-remote --tags origin v1 # must equal git rev-parse origin/main
```
**Downstream** are emowheel, which pins `cargo-cache@v1` and
`cargo-cache-publish@v1` across its CI workflow, and zemyna, migrating to the
same pin. Both pick a move up on their next run with no change on their side,
which is the whole point of the moving pointer and also the reason the move is
not automatic.
---
## Development