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:
@@ -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`
|
it forward, and anything that would break an existing consumer gets `v2`
|
||||||
instead. Pin a commit SHA if you want a frozen version.
|
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
|
## Development
|
||||||
|
|||||||
Reference in New Issue
Block a user