diff --git a/README.md b/README.md index 2daa71c..6a07994 100644 --- a/README.md +++ b/README.md @@ -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