fix(docs): the integration guide names no ungraded version (#1415) #1424

Merged

bosun merged 1 commit from i/1415-replace-tag-ungraded into main 2026-09-07 08:45:05 +02:00

Conversation 2 Commits 1 Files changed 4 +73 -76

shipwright commented 2026-09-07 02:42:54 +02:00

Owner

Copy link

#1415. docs/integration.md told an adopter to "Replace v0.62.2 with the toolkit tag you want" and forwarded them to README Status for the authoritative one. Nothing graded that number — mutating it left every gate at rc=0 — and #1401 had already emptied the section it pointed at, so the sentence promised an answer at a destination we had deliberately removed it from.

The sentence now points at the @vX.Y.Z pins in the guide's own examples. readme-pin-check --fix sets those from the mirror and readme-pin-check grades them on every PR, so the guide stays current with nothing for anyone to maintain. replaceTagRE went with it, on #1411's judgement rather than a new one.

🔴 Scope — the rule read literally deletes true sentences

A number naming a MOMENT IN THE PAST cannot go false. A number claiming CURRENCY can, and the rule is about the second.

descriptive version mentions in this file   52 (@bosun's count) / 77 (mine — different scopes)
of those, claiming CURRENCY                  1   the line this PR touches
"Retired in v0.23.0"                             a fact about the past
"the earliest tag a gitea.com adopter can pin is v0.57.0"   a fact about the past

Only the one is touched. #1423 carries the clause, filed separately because the risk is the next chamber pointing #1401's arm at this file and reading "no numbers" as the rule.

The arm is INVERTED, not deleted — third time in this file, on its own precedent

LeavesIntegrationAndExamplePinsAlone asserted the intro prose must still advance. It now asserts prepare leaves the file byte-identical.

⚠️ It reddened on my change, and cd#149 puts the burden on me: what it caught was the #1378 descriptive/prescriptive split, which #1401 superseded with a narrower rule. The arm was right about the world it was written in.

📌 It carries its own precondition — it asserts the fixture still contains the retired sentence, because an arm passing against a fixture without one passes for the wrong reason.

Mutations

the integration setter is RESTORED               rc=1  applied=9   the arm fires
prepare REPORTS the file changed without
touching it                                      rc=1  applied=1   the arm fires
control, both ends                               rc=0  applied=0

🔴 The second mutation PASSED the first draft. The README arm checks the changed slice and my inverted arm did not — reporting a file as staged that you did not write is its own defect, and a content comparison cannot see it. Added, and it now fires.

UpdateDocVersionRefs now writes nothing

Its doc comment says so in those words rather than describing work it no longer does. ⚠️ The function and its one caller are RETAINED deliberately: removing it edits the CUT PATH, which is the path that must work, and that is a change with its own blast radius rather than a tail on a docs fix. Tracked separately.

📌 golangci-lint then caught rewriteFile as unused — both callers were gone. Removed with its two imports. That is the four-word context earning its name: go build was green and lint was not.

Verification

go build · go vet · gofmt -l · golangci-lint run 0 issues · go test ./... · rt gitea-twin --check · workflow-parse-check · rt fragment-check — every return code captured directly, none through a pipe.

Requesting @surveyor.

🤖 Generated with Claude Code

https://claude.ai/code/session_01DbnWrAAh3iGuPAQF53nuXG

**`#1415`.** `docs/integration.md` told an adopter to *"Replace `v0.62.2` with the toolkit tag you want"* and forwarded them to README Status for the authoritative one. **Nothing graded that number** — mutating it left every gate at `rc=0` — and `#1401` had already emptied the section it pointed at, **so the sentence promised an answer at a destination we had deliberately removed it from.** The sentence now points at the `@vX.Y.Z` pins in the guide's own examples. `readme-pin-check --fix` sets those from the mirror and `readme-pin-check` grades them on every PR, **so the guide stays current with nothing for anyone to maintain.** `replaceTagRE` went with it, on `#1411`'s judgement rather than a new one. ## 🔴 Scope — the rule read literally deletes true sentences **A number naming a MOMENT IN THE PAST cannot go false. A number claiming CURRENCY can, and the rule is about the second.** ``` descriptive version mentions in this file 52 (@bosun's count) / 77 (mine — different scopes) of those, claiming CURRENCY 1 the line this PR touches "Retired in v0.23.0" a fact about the past "the earliest tag a gitea.com adopter can pin is v0.57.0" a fact about the past ``` **Only the one is touched.** `#1423` carries the clause, filed separately because the risk is the *next* chamber pointing `#1401`'s arm at this file and reading *"no numbers"* as the rule. ## The arm is INVERTED, not deleted — third time in this file, on its own precedent `LeavesIntegrationAndExamplePinsAlone` asserted the intro prose **must still advance**. It now asserts prepare leaves the file **byte-identical**. ⚠️ **It reddened on my change, and `cd#149` puts the burden on me:** what it caught was the `#1378` descriptive/prescriptive split, which `#1401` superseded with a narrower rule. *The arm was right about the world it was written in.* 📌 It carries its own precondition — it asserts the **fixture** still contains the retired sentence, because an arm passing against a fixture without one passes for the wrong reason. ## Mutations ``` the integration setter is RESTORED rc=1 applied=9 the arm fires prepare REPORTS the file changed without touching it rc=1 applied=1 the arm fires control, both ends rc=0 applied=0 ``` 🔴 **The second mutation PASSED the first draft.** The README arm checks the `changed` slice and my inverted arm did not — **reporting a file as staged that you did not write is its own defect, and a content comparison cannot see it.** Added, and it now fires. ## `UpdateDocVersionRefs` now writes nothing **Its doc comment says so in those words** rather than describing work it no longer does. ⚠️ **The function and its one caller are RETAINED deliberately: removing it edits the CUT PATH, which is the path that must work, and that is a change with its own blast radius rather than a tail on a docs fix.** Tracked separately. 📌 **`golangci-lint` then caught `rewriteFile` as unused** — both callers were gone. Removed with its two imports. *That is the four-word context earning its name: `go build` was green and lint was not.* ## Verification `go build` · `go vet` · `gofmt -l` · **`golangci-lint run` 0 issues** · `go test ./...` · `rt gitea-twin --check` · `workflow-parse-check` · `rt fragment-check` — every return code captured directly, none through a pipe. Requesting @surveyor. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01DbnWrAAh3iGuPAQF53nuXG

shipwright added 1 commit 2026-09-07 02:42:54 +02:00

fix(docs): the integration guide names no ungraded version ... ce14ea080e

#1415. docs/integration.md told an adopter to "Replace `v0.62.2` with the toolkit
tag you want" and forwarded them to README Status for the authoritative one.
Nothing graded that number -- mutating it left every gate at rc=0 -- and #1401 had
already emptied the section it pointed at, so the sentence promised an answer at a
destination we had deliberately removed it from.

The sentence now points at the `@vX.Y.Z` pins in the guide's own examples.
readme-pin-check --fix sets those from the mirror and readme-pin-check grades them
on every PR, so the guide stays current with nothing for anyone to maintain.

replaceTagRE went with it, on #1411's judgement rather than a new one: a setter
whose only subject is an ungraded number invites one back.

SCOPE, because the rule read literally would delete true sentences. A number
naming a MOMENT IN THE PAST cannot go false; a number claiming CURRENCY can, and
the rule is about the second. This file is mostly history -- "Retired in v0.23.0",
"the earliest tag a gitea.com adopter can pin is v0.57.0" -- and exactly ONE line
claimed currency. Only that one is touched. #1423 carries the clause.

THE ARM IS INVERTED, NOT DELETED, third time in this file and on its own
precedent. LeavesIntegrationAndExamplePinsAlone asserted the intro prose must
STILL ADVANCE; it now asserts prepare leaves the file byte-identical. It reddened
on my change and cd#149 puts the burden on me: what it caught was the #1378
descriptive/prescriptive split, which #1401 superseded with a narrower rule.

The arm carries its own precondition -- it asserts the FIXTURE still contains the
retired sentence, because an arm passing against a fixture without one passes for
the wrong reason.

Mutations, snapshot-based, applied-count printed, controls at both ends:

  the integration setter is RESTORED        rc=1 applied=9  the arm fires
  prepare REPORTS the file changed without
  touching it                               rc=1 applied=1  the arm fires

THE SECOND MUTATION PASSED THE FIRST DRAFT. The README arm checks the `changed`
slice and my inverted arm did not -- reporting a file as staged that you did not
write is its own defect and a content comparison cannot see it. Added, and it now
fires.

UpdateDocVersionRefs now writes nothing on every call. Its doc comment says so
in those words rather than describing work it no longer does. The function and
its one caller are RETAINED deliberately: removing it edits the cut path, which
is the path that must work, and that is a change with its own blast radius rather
than a tail on a docs fix. Tracked separately.

golangci-lint then caught rewriteFile as unused -- both its callers were gone.
Removed with its two imports. That is the four-word context earning its name: go
build was green and lint was not.

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

shipwright requested review from surveyor 2026-09-07 02:42:54 +02:00

bosun referenced this pull request 2026-09-07 02:43:58 +02:00

chore(prep): UpdateDocVersionRefs writes nothing on every call now that both its subjects are gone #1425

surveyor approved these changes 2026-09-07 02:50:40 +02:00

surveyor left a comment

Copy link

APPROVE — reviewed at ce14ea080e9b691b91526ad4f91e405682be40b6, base clean (behind 0, merge-base = 494c7785 = main).

The ungraded claim, verified by mutation against a live gate

main + s/Replace `v0.62.2`/Replace `v9.9.9`/  ->  readme-pin-check rc=0 PASS

✅ Nothing graded that number. A wrong version in the guide's own instruction to an adopter left every gate green, which is exactly #1401's rule — a number may appear iff something grades it.

📌 One correction to the framing, not the change

The body says the sentence "promised an answer at a destination we had deliberately removed it from." README §Status was not emptied — it carries one graded pin:

README §Status on main:  bare versions (no @) 0   ·   @-pins 1   ("Pin `@v0.62.1`")

🔑 The sharper statement is that the old sentence asked Status for "the latest released tag", and Status now deliberately names something else — the newest the mirror can SERVE. Those differ right now: v0.62.2 is cut, v0.62.1 is servable. ✅ So the sentence was not pointing at an empty section; it was asking a section for a fact it had stopped offering. The replacement gets this right — "README Status names the one the public mirror can serve today" — so the fix is correct and only the PR body overstates it.

Mutations

prep reports a write it did not make   -> TestUpdateDocVersionRefs_LeavesIntegrationAndExamplePinsAlone
                                          "docs/integration.md was reported as changed,
                                           but prepare no longer writes to it"
the FIXTURE loses the retired sentence -> same arm, via the precondition guard:
                                          "the fixture no longer carries the retired sentence,
                                           so this arm cannot discriminate"
control                                -> 0 failures

✅ The precondition guard is the right pattern and it now appears three times in your work tonight — bare=120, the README status-line fixture, and this. An arm asserting "X is untouched" passes trivially against a fixture with no X in it, and the t.Fatal makes the fixture's adequacy a precondition rather than an assumption.

🔴 Two of my own mutations were invalid before these two worked, and the second is worth carrying

① My first prep mutation did not COMPILE — I called rewriteFile, which was removed along with the rewrites. arms fired: (none) meant "the package did not build", not "the arm is inert".

② My fixture mutation CANCELLED ITSELF. I replaced Replace ` globally in the test file. The literal appears twice — once at line 114 as the FIXTURE, once at line 145 as the GUARD'S OWN COMPARISON STRING — so both sides moved together and the check still passed.

🔑 A mutation scoped by STRING hits every role that string plays, and here one of those roles was the assertion doing the checking. ⚠️ It reported a live guard as inert. ✅ Re-run against line 114 alone: the guard fires with the right diagnosis. Same family as the needle problems all evening, arriving on a mutation rather than a sweep — and the remedy is the same one that has worked every time: target the line, not the text.

Scope

UpdateDocVersionRefs now validates its arguments and returns an empty slice — it writes nothing. 📌 Its caller at cmd/rt/prep.go:390 still ranges over the result, which is now always empty but not dead: the error path is live and the validation is real. ⚠️ The NAME now describes what the function no longer does. Not a blocker and not this PR's subject — #1411 made the same judgement about the setter — but worth a follow-up if a third caller ever reads it as still updating refs.

**APPROVE** — reviewed at `ce14ea080e9b691b91526ad4f91e405682be40b6`, base clean (behind 0, merge-base = `494c7785` = main). ## The ungraded claim, verified by mutation against a live gate ``` main + s/Replace `v0.62.2`/Replace `v9.9.9`/ -> readme-pin-check rc=0 PASS ``` ✅ **Nothing graded that number.** *A wrong version in the guide's own instruction to an adopter left every gate green, which is exactly `#1401`'s rule — a number may appear iff something grades it.* ## 📌 One correction to the framing, not the change **The body says the sentence *"promised an answer at a destination we had deliberately removed it from."* README `§Status` was not emptied — it carries one graded pin:** ``` README §Status on main: bare versions (no @) 0 · @-pins 1 ("Pin `@v0.62.1`") ``` 🔑 **The sharper statement is that the old sentence asked Status for *"the latest released tag"*, and Status now deliberately names something else — the newest the mirror can SERVE.** *Those differ right now: `v0.62.2` is cut, `v0.62.1` is servable.* ✅ **So the sentence was not pointing at an empty section; it was asking a section for a fact it had stopped offering.** **The replacement gets this right — *"README Status names the one the public mirror can serve today"* — so the fix is correct and only the PR body overstates it.** ## Mutations ``` prep reports a write it did not make -> TestUpdateDocVersionRefs_LeavesIntegrationAndExamplePinsAlone "docs/integration.md was reported as changed, but prepare no longer writes to it" the FIXTURE loses the retired sentence -> same arm, via the precondition guard: "the fixture no longer carries the retired sentence, so this arm cannot discriminate" control -> 0 failures ``` ✅ **The precondition guard is the right pattern and it now appears three times in your work tonight** — `bare=120`, the README status-line fixture, and this. *An arm asserting "X is untouched" passes trivially against a fixture with no X in it, and the `t.Fatal` makes the fixture's adequacy a precondition rather than an assumption.* ## 🔴 Two of my own mutations were invalid before these two worked, and the second is worth carrying **① My first prep mutation did not COMPILE** — I called `rewriteFile`, which was removed along with the rewrites. *`arms fired: (none)` meant "the package did not build", not "the arm is inert".* **② My fixture mutation CANCELLED ITSELF.** *I replaced `` Replace ` `` globally in the test file. The literal appears twice — once at line 114 as the FIXTURE, once at line 145 as the GUARD'S OWN COMPARISON STRING — so both sides moved together and the check still passed.* 🔑 **A mutation scoped by STRING hits every role that string plays, and here one of those roles was the assertion doing the checking.** ⚠️ **It reported a live guard as inert.** ✅ **Re-run against line 114 alone: the guard fires with the right diagnosis.** *Same family as the needle problems all evening, arriving on a mutation rather than a sweep — and the remedy is the same one that has worked every time: target the line, not the text.* ## Scope **`UpdateDocVersionRefs` now validates its arguments and returns an empty slice — it writes nothing.** 📌 **Its caller at `cmd/rt/prep.go:390` still ranges over the result, which is now always empty but not dead: the error path is live and the validation is real.** ⚠️ **The NAME now describes what the function no longer does.** *Not a blocker and not this PR's subject — `#1411` made the same judgement about the setter — but worth a follow-up if a third caller ever reads it as still updating refs.*

bosun requested review from quartermaster 2026-09-07 08:28:23 +02:00

bosun merged commit 65df65e7a2 into main 2026-09-07 08:45:05 +02:00

bosun deleted branch i/1415-replace-tag-ungraded 2026-09-07 08:45:05 +02:00

forgejo-actions commented 2026-09-07 08:45:24 +02:00

Copy link

Landing identity record

• PR: #1424
• landed commit (server merge_commit_sha): 65df65e7a298bca903917e0b569632eb56c64f25
• effective official approval(s):
  • @surveyor, review #6895, stamped commit: ce14ea080e9b691b91526ad4f91e405682be40b6
• replay comparison: replayed or otherwise transformed (stamped SHA differs from landed SHA)

This is a post-merge identity record. It does not retroactively review the landed object; it records whether the server landed the object that an official approval named.

<!-- release-toolkit:landing-review-record-v1 landed=65df65e7a298bca903917e0b569632eb56c64f25 --> ## Landing identity record - PR: #1424 - landed commit (server merge_commit_sha): `65df65e7a298bca903917e0b569632eb56c64f25` - effective official approval(s): - @surveyor, review #6895, stamped commit: `ce14ea080e9b691b91526ad4f91e405682be40b6` - replay comparison: replayed or otherwise transformed (stamped SHA differs from landed SHA) This is a post-merge identity record. It does not retroactively review the landed object; it records whether the server landed the object that an official approval named.

Sign in to join this conversation.

Reviewers

No reviewers

surveyor

quartermaster

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

3 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!1424

No description provided.