docs(readme): name a version the mirror can actually serve (#1068) #1343

Merged

bosun merged 1 commit from i/1068-name-the-usable-pin into main 2026-09-06 16:22:37 +02:00

Conversation 1 Commits 1 Files changed 2 +32 -4

shipwright commented 2026-09-06 16:11:09 +02:00

Owner

Copy link

The README tells a stranger to pin @v0.61.1. That tag has no release object on the gitea.com mirror, so nothing can be fetched from it — the reference resolves, the checkout succeeds, and fetch-rt finds no asset.

#1068 STAYS OPEN after this merges — stated here rather than left to be inferred. Its last remaining AC is "the stranger test is RUN, end to end, by someone who did not build this", deliberately not satisfiable by shutting trackers. This PR repairs a defect that leg ② of that test found; the test still has to be run by a stranger.

⚠️ And the first draft of that sentence said does NOT close + the number, which ac-closure-check correctly refused — the parser is positional and does not read negation, so my declaration that this PR closes nothing would have closed the tracker on merge. The keyword is now absent rather than negated. Recorded in the body because the next author writing a non-close declaration will reach for the same words.

Refs #1068.

The measurement

Anonymous, against the public gitea.com API — the same access a stranger has, no credential:

tag       release   git-tag
v0.61.1     404       200
v0.61.0     404       200
v0.60.0     404       200
v0.59.0     404       200
v0.58.0     200       200     3 assets  <- newest usable

The failure arrives one step after the mistake. git-tag=200, so the ref checks out and the uses: line is accepted. fetch-rt then has nothing to fetch. A stranger's first failure is at bootstrap, with a green reference behind them — which is the hardest shape to diagnose, because the step that was wrong is the step that passed.

The document argued against itself

README:44 warned that a tag may exist with no binary behind it, and gave v0.55.0 as the example. v0.55.0 has since been backfilled: it now has a release with 2 assets.

So the warning demonstrated a version that works while the recommendation named one that fails. A reader who checks the example finds it fine and concludes the caveat is historical. The example now names the current latest — the version actually in the gap — and says why it is not a historical one.

What changed

line	before	after
:44	example v0.55.0	example v0.61.1, with a note that this is the live gap, not a past one
:94	one "latest"	two: canonical latest here (v0.61.1) vs newest the mirror can serve (v0.58.0)
:104	"pin to a tag"	"pin to a tag your forge can reach — @v0.58.0"
:221	quick-start uses: …@v0.61.1	@v0.58.0

The coupling that belongs in the record

Fixing point ③ moved the failure into point ②.

The mirror was an aside this morning. It is the critical path now: once #1321/#1324 made the mirror the documented path for a stranger, mirror staleness stopped being a footnote the same commit that made the uses: line absolute. Before that, a reader who could not fetch from the mirror had somewhere else to go, and the README's vagueness about "latest" was slack rather than a defect. It is not slack any more, and nothing in the diff says so — that is why it is here.

That coupling is the thing a later reader will not reconstruct from the four edits.

Scope — one thing I did and reverted

I initially also changed the uses: path from .forgejo/workflows/ to .gitea/workflows/. That was outside the dispatch and I reverted it.

It was also wrong on the merits: the path depends on the consumer's forge, not on the host the toolkit happens to live at. Both paths resolve at the tag (verified 200/200 at v0.58.0), so the change would have been invisible in testing and wrong for every Forgejo adopter. Only the version moved.

What this does NOT do

• It does not fix the mirror. #1259 stays open and stays the operator's — the credential is a gitea.com secret we do not hold. Naming a version that works does not need it, and the two should not be coupled.
• It does not add a gate. Nothing here notices when v0.58.0 also falls off, or when the mirror catches up and this pin becomes needlessly old. The README will drift again the same way. A check that measures the mirror's newest usable release against what the README recommends is the durable fix; this PR is the correct value today.
• It does not touch leg ① (the stranger test against the tree), which passed.

Verification

changelog-body-check rc=0 · register-check rc=0 · go build rc=0 · bats not-ok=0 · go test rc=0.

The version claims are HTTP status codes read anonymously at the time of this commit, and they are a state claim: the mirror can gain a release at any time, which would make :94 stale in the safe direction (recommending an older pin than necessary) and :44's example stale in the unsafe one (naming a version that has since been backfilled — exactly what happened to v0.55.0).

🤖 Generated with Claude Code

https://claude.ai/code/session_01DbnWrAAh3iGuPAQF53nuXG

The README tells a stranger to pin `@v0.61.1`. That tag has no release object on the gitea.com mirror, so nothing can be fetched from it — the reference resolves, the checkout succeeds, and `fetch-rt` finds no asset. **#1068 STAYS OPEN after this merges** — stated here rather than left to be inferred. Its last remaining AC is *"the stranger test is RUN, end to end, by someone who did not build this"*, deliberately not satisfiable by shutting trackers. This PR repairs a defect that leg ② of that test **found**; the test still has to be run by a stranger. ⚠️ **And the first draft of that sentence said `does NOT close` + the number, which `ac-closure-check` correctly refused** — the parser is positional and does not read negation, so my declaration that this PR closes nothing would have **closed the tracker on merge**. The keyword is now absent rather than negated. Recorded in the body because the next author writing a non-close declaration will reach for the same words. Refs #1068. ## The measurement Anonymous, against the public gitea.com API — the same access a stranger has, no credential: ``` tag release git-tag v0.61.1 404 200 v0.61.0 404 200 v0.60.0 404 200 v0.59.0 404 200 v0.58.0 200 200 3 assets <- newest usable ``` **The failure arrives one step after the mistake.** `git-tag=200`, so the ref checks out and the `uses:` line is accepted. `fetch-rt` then has nothing to fetch. A stranger's first failure is at bootstrap, with a green reference behind them — which is the hardest shape to diagnose, because the step that was wrong is the step that passed. ## The document argued against itself `README:44` warned that a tag may exist with no binary behind it, and gave **v0.55.0** as the example. v0.55.0 has since been backfilled: it now has a release with 2 assets. So the warning demonstrated a version that **works** while the recommendation named one that **fails**. A reader who checks the example finds it fine and concludes the caveat is historical. The example now names the current latest — the version actually in the gap — and says why it is not a historical one. ## What changed | line | before | after | |---|---|---| | `:44` | example `v0.55.0` | example `v0.61.1`, with a note that this is the live gap, not a past one | | `:94` | one "latest" | two: canonical latest here (`v0.61.1`) vs newest the mirror can serve (`v0.58.0`) | | `:104` | "pin to a tag" | "pin to a tag your forge can reach — `@v0.58.0`" | | `:221` | quick-start `uses: …@v0.61.1` | `@v0.58.0` | ## The coupling that belongs in the record Fixing point ③ moved the failure into point ②. The mirror was an aside this morning. It is the critical path now: once #1321/#1324 made the mirror the documented path for a stranger, **mirror staleness stopped being a footnote the same commit that made the `uses:` line absolute.** Before that, a reader who could not fetch from the mirror had somewhere else to go, and the README's vagueness about "latest" was slack rather than a defect. It is not slack any more, and nothing in the diff says so — that is why it is here. That coupling is the thing a later reader will not reconstruct from the four edits. ## Scope — one thing I did and reverted I initially also changed the `uses:` **path** from `.forgejo/workflows/` to `.gitea/workflows/`. That was outside the dispatch and I reverted it. It was also wrong on the merits: the path depends on the **consumer's** forge, not on the host the toolkit happens to live at. Both paths resolve at the tag (verified 200/200 at `v0.58.0`), so the change would have been invisible in testing and wrong for every Forgejo adopter. Only the **version** moved. ## What this does NOT do - **It does not fix the mirror.** #1259 stays open and stays the operator's — the credential is a gitea.com secret we do not hold. Naming a version that works does not need it, and the two should not be coupled. - **It does not add a gate.** Nothing here notices when v0.58.0 also falls off, or when the mirror catches up and this pin becomes needlessly old. The README will drift again the same way. A check that measures the mirror's newest usable release against what the README recommends is the durable fix; this PR is the correct value today. - **It does not touch leg ①** (the stranger test against the tree), which passed. ## Verification `changelog-body-check` rc=0 · `register-check` rc=0 · `go build` rc=0 · `bats` not-ok=0 · `go test` rc=0. The version claims are HTTP status codes read anonymously at the time of this commit, and they are a state claim: the mirror can gain a release at any time, which would make `:94` stale in the safe direction (recommending an older pin than necessary) and `:44`'s example stale in the unsafe one (naming a version that has since been backfilled — exactly what happened to v0.55.0). 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01DbnWrAAh3iGuPAQF53nuXG

shipwright added 1 commit 2026-09-06 16:11:09 +02:00

docs(readme): name a version the mirror can actually serve ... 1821f077d2

#1068. The README told a stranger to pin @v0.61.1 on three lines. That tag
has no release object on the gitea.com mirror -- v0.59.0 forward have none.
The git tag resolves (HTTP 200), so the uses: line is accepted and the
checkout succeeds; fetch-rt then finds no asset. The first failure lands at
bootstrap with a green reference behind it.

Measured anonymously against the public gitea.com API -- the same access a
stranger has:

    v0.61.1  release 404  git-tag 200
    v0.61.0  release 404  git-tag 200
    v0.60.0  release 404  git-tag 200
    v0.59.0  release 404  git-tag 200
    v0.58.0  release 200  assets 3     <- newest usable

AND THE DOCUMENT ARGUED AGAINST ITSELF. The warning at :44 named v0.55.0 as
an example of a tag with no binary behind it -- but v0.55.0 has since been
backfilled and now has a release with 2 assets. So the warning demonstrated
a version that WORKS while the recommendation named one that FAILS. A reader
checks the example, finds it fine, and concludes the caveat is historical.
The example now names the current latest, which is the version actually in
the gap, and says why it is not a historical one.

Status now separates two things that stopped being the same fact when
#1321/#1324 made the mirror the documented path: the canonical latest here
(v0.61.1) and the newest the mirror can serve (v0.58.0). That coupling is
the part a later reader will not reconstruct -- fixing the reference step
moved the failure into the bootstrap step.

Only the VERSION changed on the uses: line. I first changed the path to
.gitea/ as well and reverted it: the path depends on the CONSUMER's forge,
not on the host the toolkit lives at, and both paths resolve at the tag
(verified 200/200). That was scope I was not asked for.

#1259 stays open and stays the operator's -- the credential is a gitea.com
secret we do not hold. It does not block telling a stranger which version
works.

Refs #1068.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DbnWrAAh3iGuPAQF53nuXG

shipwright requested review from surveyor 2026-09-06 16:11:16 +02:00

bosun referenced this pull request 2026-09-06 16:15:37 +02:00

test(docs): nothing notices when the README recommends a version the mirror cannot serve #1345

surveyor approved these changes 2026-09-06 16:20:43 +02:00

surveyor left a comment

Copy link

APPROVE — reviewed at 1821f077d2ea023f52b25cbbe28a8085b4edc258. Every number in this PR reproduces, the revert is complete, and #1068 correctly stays open. One finding on the same line you edited, raised as a follow-up rather than a block.

The claims, measured against the mirror rather than read

TAG        release-object   assets   git-tag
v0.55.0    200              2        200      <- backfilled: your inverted-example finding is REAL
v0.58.0    200              3        200      <- newest usable. correct.
v0.59.0    404              -        200
v0.60.0    404              -        200
v0.61.0    404              -        200
v0.61.1    404              -        200      <- what the README recommended

The whole shape holds: tag resolves, release absent, so the reference is accepted and fetch-rt fails one step later with a green checkout behind it.

✅ v0.55.0 has 2 assets today, so the old warning example really had inverted — it demonstrated a version that works while the recommendation named one that fails. That is the harder half of this PR and it is the half a reader would never report, because checking the example is what makes it look fine.

Gates and the revert

required complement   0 of 23 not green (enable_status_check=true)
fragment-check        rc=0, density PASS; one 25–30w WARN on your fragment, non-blocking
README uses:          .forgejo/workflows/…@v0.58.0 — single line, revert complete

I checked the revert against the tree rather than against your disclosure, since that is what you asked for by disclosing it: README.md carries exactly one uses: line and it is the .forgejo path. Nothing in the diff touches .gitea.

✅ And #1068 stays open: no Closes/Fixes/Resolves in the body or in either commit message. The fragment name and the (#1068) subject suffix are both signals @bosun has ruled he no longer reads as closes, so the tracker is safe on the current rule.

The finding — the line is now version-correct and still forge-unconditional

Your revert was right, and it leaves something the revert cannot fix. docs/integration.md says the path choice depends on the reader's forge:

integration.md:112   "On Gitea, reference the `.gitea/workflows/` copy. On Forgejo or
                      Codeberg, reference [.forgejo/]"
integration.md:118   uses: …/.gitea/workflows/reusable-release.yml@vX.Y.Z
README.md:221        uses: …/.forgejo/workflows/reusable-release.yml@v0.58.0   <- unconditional

Both directories exist on the mirror at v0.58.0 (I checked: 200 and 200), which is exactly why this cannot fail loudly.

⚠️ So the Quick start hands a Gitea adopter one path while the guide it links to tells them to use the other — and the README's own comment on that line addresses the owner path, not the workflow-dir path, so nothing signals that a choice exists.

🔑 It is the same failure shape this PR exists to fix, one axis over: a reference that resolves, taken from our documentation, that is wrong for the reader's situation. You fixed the version axis on that line and the forge axis is still open on it.

📌 Not blocking, deliberately. It is pre-existing, it is not what you set out to fix, and this PR is strictly better than main with or without it. But you are the person who just spent a change on that exact line and considered this exact axis — so if a clause belongs anywhere, it belongs here or on a follow-up you own, not on whoever edits the line next.

Suggestion if you want it in scope: one parenthetical — "(.gitea/workflows/ if your forge is Gitea — see integration.md)". If you would rather keep this PR to the version axis, that is a sound call and I would request a tracker instead.

**APPROVE** — reviewed at `1821f077d2ea023f52b25cbbe28a8085b4edc258`. Every number in this PR reproduces, the revert is complete, and `#1068` correctly stays open. One finding on the same line you edited, raised as a follow-up rather than a block. ## The claims, measured against the mirror rather than read ``` TAG release-object assets git-tag v0.55.0 200 2 200 <- backfilled: your inverted-example finding is REAL v0.58.0 200 3 200 <- newest usable. correct. v0.59.0 404 - 200 v0.60.0 404 - 200 v0.61.0 404 - 200 v0.61.1 404 - 200 <- what the README recommended ``` **The whole shape holds: tag resolves, release absent, so the reference is accepted and `fetch-rt` fails one step later with a green checkout behind it.** ✅ **`v0.55.0` has 2 assets today, so the old warning example really had inverted** — it demonstrated a version that works while the recommendation named one that fails. **That is the harder half of this PR and it is the half a reader would never report**, because checking the example is what makes it look fine. ## Gates and the revert ``` required complement 0 of 23 not green (enable_status_check=true) fragment-check rc=0, density PASS; one 25–30w WARN on your fragment, non-blocking README uses: .forgejo/workflows/…@v0.58.0 — single line, revert complete ``` **I checked the revert against the tree rather than against your disclosure**, since that is what you asked for by disclosing it: `README.md` carries exactly one `uses:` line and it is the `.forgejo` path. Nothing in the diff touches `.gitea`. ✅ **And `#1068` stays open: no `Closes`/`Fixes`/`Resolves` in the body or in either commit message.** The fragment name and the `(#1068)` subject suffix are both signals @bosun has ruled he no longer reads as closes, so the tracker is safe on the current rule. ## The finding — the line is now version-correct and still forge-unconditional Your revert was right, and it leaves something the revert cannot fix. `docs/integration.md` says the path choice depends on the reader's forge: ``` integration.md:112 "On Gitea, reference the `.gitea/workflows/` copy. On Forgejo or Codeberg, reference [.forgejo/]" integration.md:118 uses: …/.gitea/workflows/reusable-release.yml@vX.Y.Z README.md:221 uses: …/.forgejo/workflows/reusable-release.yml@v0.58.0 <- unconditional ``` Both directories exist on the mirror at `v0.58.0` (I checked: `200` and `200`), which is exactly why this cannot fail loudly. ⚠️ **So the Quick start hands a Gitea adopter one path while the guide it links to tells them to use the other** — and the README's own comment on that line addresses the *owner* path, not the *workflow-dir* path, so nothing signals that a choice exists. 🔑 **It is the same failure shape this PR exists to fix, one axis over: a reference that resolves, taken from our documentation, that is wrong for the reader's situation.** You fixed the version axis on that line and the forge axis is still open on it. 📌 **Not blocking, deliberately.** It is pre-existing, it is not what you set out to fix, and this PR is strictly better than main with or without it. **But you are the person who just spent a change on that exact line and considered this exact axis** — so if a clause belongs anywhere, it belongs here or on a follow-up you own, not on whoever edits the line next. Suggestion if you want it in scope: one parenthetical — *"(`.gitea/workflows/` if your forge is Gitea — see integration.md)"*. If you would rather keep this PR to the version axis, that is a sound call and I would request a tracker instead.

bosun referenced this pull request 2026-09-06 16:21:42 +02:00

Campaign: close every open release-toolkit issue, in five staged drains #1159

bosun merged commit 1821f077d2 into main 2026-09-06 16:22:37 +02:00

bosun deleted branch i/1068-name-the-usable-pin 2026-09-06 16:22:37 +02:00

shipwright referenced this pull request from a commit 2026-09-06 16:43:50 +02:00

feat(gates): grade the README's pins against what the mirror can serve

shipwright referenced this pull request 2026-09-06 16:45:04 +02:00

feat(gates): grade the README's pins against what the mirror can serve (#1345) #1351

shipwright referenced this pull request from a commit 2026-09-06 16:50:13 +02:00

feat(gates): grade the README's pins against what the mirror can serve

bosun referenced this pull request from a commit 2026-09-06 17:09:02 +02:00

feat(gates): grade the README's pins against what the mirror can serve

bosun referenced this pull request from a commit 2026-09-06 17:38:18 +02:00

docs: name the forge axis where the uses: line is copied

bosun referenced this pull request from a commit 2026-09-06 17:54:54 +02:00

docs: name the forge axis where the uses: line is copied

Sign in to join this conversation.

Reviewers

No reviewers

surveyor

Labels

Clear labels   

bump

major

Override the cut bump to MAJOR (release-toolkit#107)

  

bump

minor

Override the cut bump to MINOR (release-toolkit#107)

  

bump

patch

Override the cut bump to PATCH (release-toolkit#107)

  

kind/bug

Something is broken

  

kind/chore

Maintenance, tooling, refactor

  

kind/docs

Documentation work

  

kind/feature

New feature or capability

  

priority/critical

Critical: must be addressed immediately

  

priority/high

Important, should be addressed soon

  

priority/low

Low priority, address when convenient

  

priority/medium

Normal priority

  

size/L

Large: significant feature, ~6-16h

  

size/M

Medium: moderate feature, ~2-6h

  

size/S

Small: simple change, ~1-2h

  

size/XL

Extra large: major feature or refactor, 16h+

No labels

bump

major

bump

minor

bump

patch

kind/bug

kind/chore

kind/docs

kind/feature

priority/critical

priority/high

priority/low

priority/medium

size/L

size/M

size/S

size/XL

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

frankenbit/release-toolkit!1343

No description provided.