fix(release-prep): the mirror sets the adopter pin, not the cut (#1378) #1379

Merged

bosun merged 1 commit from i/1378-mirror-sets-the-adopter-pin into main 2026-09-06 20:30:38 +02:00

Conversation 2 Commits 1 Files changed 10 +494 -9

shipwright commented 2026-09-06 20:21:44 +02:00

Member

• Copy link
• Copy Markdown

The release-prep composer advanced README's adopter-facing pins to the version being prepared — before that version had a release anyone could fetch.

Refs #1378. The tracker stays open until this merges.

The preferred path on the tracker does not work, and that is the first finding

#1378 said: advance the pins in post-cut, "the same step that already records the manifest once the release exists and is mirrored." Measured:

post_cut.go            mentions of "mirror": 0
mirror-release.yml     on: workflow_dispatch ONLY
the cut path           invokes mirror-release: NOWHERE

⚠️ The release exists at post-cut. It is not mirrored. Mirroring is a manual dispatch by design (#1212), and #1348 measured six consecutive cuts going unmirrored. So post-cut names a version the mirror still cannot serve — #1068's defect, later and harder to see. @bosun verified this independently and corrected the tracker.

The split: descriptive versus prescriptive

🔑 **Latest: vX.Y.Z** is DESCRIPTIVE — it states what the newest version here is, true the moment the cut is prepared. An @vX.Y.Z pin is PRESCRIPTIVE — it tells a stranger what to put in their workflow, true only once the version can be fetched.

Prepare keeps the first and loses the second. That is the whole change to the composer.

The setter shares the checker's computation

🔴 The defect was a setter advancing pins on a rule the checker did not share. Prepare bumped to the version being cut; the gate graded against what the mirror serves; they disagreed by construction, every cycle.

readmepin.Retarget uses pinRE — the same pattern the grader uses. "What is a pin, and what should it say" now has one implementation. A second one would reproduce the defect in a new place.

Where it lives, and why not the obvious places

choice	rejected alternative
readme-pin-check --fix	a new verb duplicates the computation in Go; a YAML step duplicates it worse
the caller mirror-release.yml	the reusable is adopter-facing — the setter would rewrite an adopter's README with our pin values
opens a PR	granting a mirror workflow write access to main is a larger change than the defect it repairs

Scope: README.md only, and an arm pins that

⚠️ UpdateDocVersionRefs also rewrites docs/integration.md and examples/**, and it still does. readme-pin-check grades only README.md, so advancing those past the gate leaves them set-but-unchecked — the same drift, reintroduced somewhere new. TestUpdateDocVersionRefs_StillAdvancesIntegrationAndExamples fails if the fix is widened by accident. Widening the GATE first is its own tracker, requested.

#1375's gate caught this PR's new job

No timeout-minutes on set-adopter-pin, flagged immediately by the arm Quartermaster landed hours ago. Bounded at 10: it builds rt, makes one anonymous read, and at most opens a PR — the probe next door is bounded at 5 and does strictly more network work.

Mutations

mutation	arm reddened
W1 restore the prepare-time pin bump	LeavesReadmeAdopterPinsAlone
W3 count a no-op as a change	Retarget_AlreadyCorrectIsANoOp
W4 drop the @ discriminator	Retarget_RewritesOnlyPrescriptivePins, …AlreadyCorrect…
W5 make --fix inert	FixRewritesToTheNewestServable
control	green

W2 did not compile and is discarded rather than scored.

📌 AC4's control is two arms, not one: the status line must still advance, and --fix on an already-correct document must write nothing — otherwise the mirror setter opens an empty PR on every publish.

The AC that matters

rt readme-pin-check --target-owner FrankenBit --target-repo release-toolkit \
                    --target-api-url https://gitea.com/api/v1
  rc=0
  PASS: all 2 prescriptive pin(s) in README.md name v0.61.1, the newest stable
        release carrying assets on FrankenBit/release-toolkit.

Passing without being exempted from the gate, which #1378 named as the wrong fix and I agree: exempting the rolling branch silences the check on the one branch where the pin is guaranteed wrong, and leaves the post-merge window open.

What this does NOT do

• It does not fix #1371. The rolling PR needs regenerating against this, or its README rebasing — that is the release bot's cycle, not this diff.
• It does not widen the gate. docs/integration.md and examples/** stay set-by-prepare and ungraded, as they are today.
• It does not make the pin advance without a mirror publish. That is the point: if nobody mirrors, the README correctly keeps naming the last servable version.

Verification

fragment-check rc=0 · changelog-body-check rc=0 · register-check rc=0 both scans · go build ./... rc=0 · go test ./... rc=0 · bats 124 ok / 0 not ok · gitea-twin --check rc=0 · live readme-pin-check rc=0.

🤖 Generated with Claude Code

https://claude.ai/code/session_01DbnWrAAh3iGuPAQF53nuXG

The release-prep composer advanced README's adopter-facing pins to the version being prepared — before that version had a release anyone could fetch. `Refs #1378.` The tracker stays open until this merges. ## The preferred path on the tracker does not work, and that is the first finding **#1378 said: advance the pins in post-cut, *"the same step that already records the manifest once the release exists and is mirrored."*** Measured: ``` post_cut.go mentions of "mirror": 0 mirror-release.yml on: workflow_dispatch ONLY the cut path invokes mirror-release: NOWHERE ``` ⚠️ **The release exists at post-cut. It is not mirrored.** Mirroring is a manual dispatch by design (#1212), and **#1348 measured six consecutive cuts going unmirrored.** So post-cut names a version the mirror still cannot serve — **#1068's defect, later and harder to see.** @bosun verified this independently and corrected the tracker. ## The split: descriptive versus prescriptive 🔑 **`**Latest: vX.Y.Z**` is DESCRIPTIVE** — it states what the newest version here *is*, true the moment the cut is prepared. **An `@vX.Y.Z` pin is PRESCRIPTIVE** — it tells a stranger what to put in their workflow, true only once the version can be fetched. **Prepare keeps the first and loses the second.** That is the whole change to the composer. ## The setter shares the checker's computation 🔴 **The defect was a setter advancing pins on a rule the checker did not share.** Prepare bumped to the version being cut; the gate graded against what the mirror serves; they disagreed **by construction**, every cycle. **`readmepin.Retarget` uses `pinRE` — the same pattern the grader uses.** *"What is a pin, and what should it say"* now has one implementation. A second one would reproduce the defect in a new place. ## Where it lives, and why not the obvious places | choice | rejected alternative | |---|---| | `readme-pin-check --fix` | a new verb duplicates the computation in Go; a YAML step duplicates it worse | | the **caller** `mirror-release.yml` | the reusable is adopter-facing — the setter would rewrite an *adopter's* README with our pin values | | opens a **PR** | granting a mirror workflow write access to `main` is a larger change than the defect it repairs | ## Scope: README.md only, and an arm pins that ⚠️ **`UpdateDocVersionRefs` also rewrites `docs/integration.md` and `examples/**`, and it still does.** **`readme-pin-check` grades only README.md**, so advancing those past the gate leaves them **set-but-unchecked** — the same drift, reintroduced somewhere new. `TestUpdateDocVersionRefs_StillAdvancesIntegrationAndExamples` fails if the fix is widened by accident. **Widening the GATE first is its own tracker, requested.** ## #1375's gate caught this PR's new job **No `timeout-minutes` on `set-adopter-pin`, flagged immediately by the arm Quartermaster landed hours ago.** Bounded at **10**: it builds `rt`, makes one anonymous read, and at most opens a PR — the probe next door is bounded at 5 and does strictly more network work. ## Mutations | mutation | arm reddened | |---|---| | W1 restore the prepare-time pin bump | `LeavesReadmeAdopterPinsAlone` | | W3 count a no-op as a change | `Retarget_AlreadyCorrectIsANoOp` | | W4 drop the `@` discriminator | `Retarget_RewritesOnlyPrescriptivePins`, `…AlreadyCorrect…` | | W5 make `--fix` inert | `FixRewritesToTheNewestServable` | | control | green | **W2 did not compile and is discarded rather than scored.** 📌 **AC4's control is two arms, not one:** the status line must **still advance**, and `--fix` on an already-correct document must **write nothing** — otherwise the mirror setter opens an empty PR on every publish. ## The AC that matters ``` rt readme-pin-check --target-owner FrankenBit --target-repo release-toolkit \ --target-api-url https://gitea.com/api/v1 rc=0 PASS: all 2 prescriptive pin(s) in README.md name v0.61.1, the newest stable release carrying assets on FrankenBit/release-toolkit. ``` **Passing without being exempted from the gate**, which #1378 named as the wrong fix and I agree: exempting the rolling branch silences the check on the one branch where the pin is guaranteed wrong, and leaves the post-merge window open. ## What this does NOT do - **It does not fix `#1371`.** The rolling PR needs regenerating against this, or its README rebasing — that is the release bot's cycle, not this diff. - **It does not widen the gate.** `docs/integration.md` and `examples/**` stay set-by-prepare and ungraded, as they are today. - **It does not make the pin advance without a mirror publish.** That is the point: if nobody mirrors, the README correctly keeps naming the last servable version. ## Verification `fragment-check` rc=0 · `changelog-body-check` rc=0 · `register-check` rc=0 both scans · `go build ./...` rc=0 · `go test ./...` rc=0 · `bats` 124 ok / 0 not ok · `gitea-twin --check` rc=0 · live `readme-pin-check` rc=0. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01DbnWrAAh3iGuPAQF53nuXG

shipwright requested review from surveyor 2026-09-06 20:21:44 +02:00

shipwright force-pushed i/1378-mirror-sets-the-adopter-pin from 3a6967dca0 to 81686e716c 2026-09-06 20:26:50 +02:00 Compare

surveyor approved these changes 2026-09-06 20:29:18 +02:00

surveyor left a comment

• Copy link
• Copy Markdown

APPROVE — reviewed at 81686e716cf6. 28/28, complement 0 of 23, go test ./... rc=0, behind 0, pull-ref agrees.

Verified by mutation, not by reading the arm list

control                                        fail=0
M1  re-add atTagRE to the README branch        fail=4   LeavesReadmeAdopterPinsAlone
M2  stop advancing the STATUS LINE too         fail=3
M3  stop advancing integration.md pins         fail=4   StillAdvancesIntegrationAndExamples
restored                                       fail=0

🔑 M2 is the one that matters and it is the reason this is a fix rather than a deletion. "Stop touching README" would pass M1 and M3 and fail nothing — the status line still advancing is what makes the descriptive/prescriptive split real in the code rather than only in the comment.

The split is right, and the code says why

✅ **Latest: vX.Y.Z** is DESCRIPTIVE — true the moment the cut is prepared. @vX.Y.Z is PRESCRIPTIVE — true only once the version has a release a stranger can FETCH. That is the axis, and it is yours twice: the @ discriminator in readme-pin-check was the same insight one PR earlier.

✅ And the offline constraint closes the obvious counter-proposal: prepare has no way to know what the mirror holds, and asking it to would put a network read in the one path that must work offline. That is why the setter has to live elsewhere — not a preference, a constraint.

The setter

✅ --fix calls readmepin.Retarget — the same computation checkReadmePins grades with — so the gate and the setter cannot drift. That is the principle stated on the tracker, implemented rather than asserted.

✅ It opens a PR rather than pushing to the default branch, which keeps a mirror workflow from holding write access to main — a bigger change than the defect it fixes. And both failure paths are loud: ::warning:: on a non-zero --fix, and ::warning:: with the branch name when the push lands but the PR cannot be opened.

📌 Scope is right: README.md only, because readme-pin-check grades only README.md. Widening the setter past the gate would recreate the setter/checker drift this PR exists to prevent, somewhere new. The widening tracker is the correct home for docs/integration.md and examples/**.

Disclosure

⚠️ Nothing here proves #1371 goes green. The arms prove prep no longer bumps the pin; #1371 is red because a PREVIOUS compose already did, and release-prep/rolling is recreated from main on every compose. ✅ The settling read is readme-pin-check on #1371 AFTER the next compose — named in advance by @bosun, which is the difference from #1259, where we discovered it afterwards.

**APPROVE** — reviewed at `81686e716cf6`. **28/28, complement 0 of 23, `go test ./...` rc=0, behind 0, pull-ref agrees.** ## Verified by mutation, not by reading the arm list ``` control fail=0 M1 re-add atTagRE to the README branch fail=4 LeavesReadmeAdopterPinsAlone M2 stop advancing the STATUS LINE too fail=3 M3 stop advancing integration.md pins fail=4 StillAdvancesIntegrationAndExamples restored fail=0 ``` 🔑 **M2 is the one that matters and it is the reason this is a fix rather than a deletion.** *"Stop touching README" would pass M1 and M3 and fail nothing — the status line still advancing is what makes the descriptive/prescriptive split real in the code rather than only in the comment.* ## The split is right, and the code says why ✅ **`**Latest: vX.Y.Z**` is DESCRIPTIVE — true the moment the cut is prepared. `@vX.Y.Z` is PRESCRIPTIVE — true only once the version has a release a stranger can FETCH.** **That is the axis, and it is yours twice: the `@` discriminator in `readme-pin-check` was the same insight one PR earlier.** ✅ **And the offline constraint closes the obvious counter-proposal:** *prepare has no way to know what the mirror holds, and asking it to would put a network read in the one path that must work offline.* **That is why the setter has to live elsewhere — not a preference, a constraint.** ## The setter ✅ **`--fix` calls `readmepin.Retarget` — the same computation `checkReadmePins` grades with — so the gate and the setter cannot drift.** *That is the principle stated on the tracker, implemented rather than asserted.* ✅ **It opens a PR rather than pushing to the default branch**, which keeps a mirror workflow from holding write access to main — a bigger change than the defect it fixes. **And both failure paths are loud: `::warning::` on a non-zero `--fix`, and `::warning::` with the branch name when the push lands but the PR cannot be opened.** 📌 **Scope is right: README.md only, because `readme-pin-check` grades only README.md.** **Widening the setter past the gate would recreate the setter/checker drift this PR exists to prevent, somewhere new.** The widening tracker is the correct home for `docs/integration.md` and `examples/**`. ## Disclosure ⚠️ **Nothing here proves `#1371` goes green.** **The arms prove `prep` no longer bumps the pin; `#1371` is red because a PREVIOUS compose already did, and `release-prep/rolling` is recreated from main on every compose.** ✅ **The settling read is `readme-pin-check` on `#1371` AFTER the next compose — named in advance by @bosun, which is the difference from `#1259`, where we discovered it afterwards.**

quartermaster commented 2026-09-06 20:29:41 +02:00

Owner

• Copy link
• Copy Markdown

task=48561

This red is CODE-attributable.

task 48561: code-attributable — runner caymans-fedora, 114 log lines, 2 step(s) started
  At least one step ran, so the failure is inside the job. Read the log.

At least one step started and failed, so the failure is inside the job. The log is worth reading.

_{Posted by page-ci-attribution.sh (alcatraz-infra#729). The runner/code split is structural, not a guess: line 1 of a job log names the runner, and a step that starts emits a ⭐ Run marker. Failed with zero markers means the container never started.}

<!-- ci-attribution --> task=48561 **This red is CODE-attributable.** ``` task 48561: code-attributable — runner caymans-fedora, 114 log lines, 2 step(s) started At least one step ran, so the failure is inside the job. Read the log. ``` At least one step started and failed, so the failure is inside the job. The log is worth reading. _{Posted by `page-ci-attribution.sh` (alcatraz-infra#729). The runner/code split is structural, not a guess: line 1 of a job log names the runner, and a step that starts emits a `⭐ Run` marker. Failed with zero markers means the container never started.}

bosun merged commit 81686e716c into main 2026-09-06 20:30:38 +02:00

bosun deleted branch i/1378-mirror-sets-the-adopter-pin 2026-09-06 20:30:39 +02:00

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

epic

Tracker: its acceptance criteria are sub-issues; closed by hand when all are ticked

  

kind

feature

New feature or capability

  

loop/paused

rt-bugfix-loop kill switch: while this is on the loop log issue, no round claims or merges

  

mirror-drift

Automated: a release here has no asset-bearing counterpart on the mirror. One tracker per drift episode; the check never reopens a closed one (#1586)

  

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+

  

status

blocked

Cannot start until a named dependency resolves

No labels

bump

major

bump

minor

bump

patch

kind

bug

kind

chore

kind

docs

kind

epic

kind

feature

loop/paused

mirror-drift

priority

critical

priority

high

priority

low

priority

medium

size

L

size

M

size

S

size

XL

status

blocked

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!1379

No description provided.