docs(gates): record why base-divergence-check stays advisory #1358

Merged

bosun merged 1 commit from i/1312-advisory-reason into main 2026-09-06 17:43:56 +02:00

Conversation 2 Commits 1 Files changed 2 +45

bosun commented 2026-09-06 17:23:57 +02:00

Owner

Copy link

Records the operator's decision on #1312 where the next person proposing promotion will meet it: the verb's own doc comment, not the tracker.

Decision, 2026-09-06: keep base-divergence-check ADVISORY. The operator's reason, in his words — "While it may break release-toolkit, it should not break the adopters. At least the ones pinned to a release."

Why the comment carries the evidence and not just the verdict

A decision without its measurements gets re-litigated from scratch by whoever next notices a red advisory context. Three measurements are recorded with it:

redundant with the required set   #1195's landing-tree replay is in 19 of 35 workflows,
                                  covers all 23 required contexts, and resolves its base
                                  from github.base_ref and fetches origin/$BASE_REF AT
                                  RUN TIME. This verb reports the branch's STORED
                                  merge-base — a different object, a weaker claim.
required-and-stale                it does not re-run when the base moves (its own PASS
                                  says so), and main took 131 commits that day.
the cost                          78 merges, 59 behind by >=1, 23 behind by >=10, max 24,
                                  against dismiss_stale_approvals=true.

And the counterweight, deliberately

So the comment is not read as a claim that divergence is harmless: it HAS bitten. #1141/#1143 and the 25-minute main breakage recorded on #1195 are real.

But those were semantic collisions between changes to different files, and this verb measures DISTANCE, not compatibility. It would not have caught either. The gate is not the remedy for the failure it is associated with — which is the strongest argument against promoting it and the one most likely to be lost.

The comment closes by naming what does protect a merge: replaying the PR onto live main at the moment of the merge, with a control that deliberately conflicts. That cannot expire, because nothing can move between it and the merge.

Gates

build · vet · golangci-lint (0 issues) · go test · fragment-check · register-check   all rc=0

Intended-targets: #1312

Closes #1312

🤖 Generated with Claude Code

https://claude.ai/code/session_01LgsJZGnWyfvJZYqDEK48yb

Records the operator's decision on `#1312` where the next person proposing promotion will meet it: the verb's own doc comment, not the tracker. **Decision, 2026-09-06: keep `base-divergence-check` ADVISORY.** The operator's reason, in his words — *"While it may break release-toolkit, it should not break the adopters. At least the ones pinned to a release."* ## Why the comment carries the evidence and not just the verdict A decision without its measurements gets re-litigated from scratch by whoever next notices a red advisory context. Three measurements are recorded with it: ``` redundant with the required set #1195's landing-tree replay is in 19 of 35 workflows, covers all 23 required contexts, and resolves its base from github.base_ref and fetches origin/$BASE_REF AT RUN TIME. This verb reports the branch's STORED merge-base — a different object, a weaker claim. required-and-stale it does not re-run when the base moves (its own PASS says so), and main took 131 commits that day. the cost 78 merges, 59 behind by >=1, 23 behind by >=10, max 24, against dismiss_stale_approvals=true. ``` ## And the counterweight, deliberately So the comment is not read as a claim that divergence is harmless: it HAS bitten. `#1141`/`#1143` and the 25-minute main breakage recorded on `#1195` are real. But those were semantic collisions between changes to different files, and this verb measures DISTANCE, not compatibility. It would not have caught either. The gate is not the remedy for the failure it is associated with — which is the strongest argument against promoting it and the one most likely to be lost. The comment closes by naming what does protect a merge: replaying the PR onto live main at the moment of the merge, with a control that deliberately conflicts. That cannot expire, because nothing can move between it and the merge. ## Gates ``` build · vet · golangci-lint (0 issues) · go test · fragment-check · register-check all rc=0 ``` Intended-targets: #1312 Closes #1312 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01LgsJZGnWyfvJZYqDEK48yb

bosun added 1 commit 2026-09-06 17:23:57 +02:00

docs(gates): record why base-divergence-check stays advisory ... 140869e8c8

Operator decision, 2026-09-06, after the options were costed on #1312: keep it
advisory. His reason is that a divergence-caused breakage lands on
release-toolkit and not on adopters pinned to a release, and this project
publishes pinnable stable releases precisely so that holds.

The AC asked for the reason to be written where the next person proposing
promotion will read it. That is the verb's own doc comment, not the tracker.

Three measurements are recorded with it, because a decision without its
evidence gets re-litigated from scratch:

  redundant with the required set  #1195's landing-tree replay is in 19 of 35
                                   workflows, covers all 23 required contexts,
                                   and resolves its base from github.base_ref at
                                   RUN TIME. This verb reports the branch's
                                   STORED merge-base — a weaker claim.
  required-and-stale               it does not re-run when the base moves, and
                                   main took 131 commits that day.
  the cost                         59 of 78 merges were behind, 23 by ten or
                                   more, max 24, against dismiss_stale_approvals.

And the counterweight, so the comment is not read as "divergence is harmless":
it HAS bitten (#1141/#1143, the 25-minute main breakage on #1195). Those were
semantic collisions between different files; this verb measures DISTANCE, not
compatibility, and would not have caught either.

Intended-targets: #1312

Closes #1312

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

bosun requested review from surveyor 2026-09-06 17:23:57 +02:00

surveyor approved these changes 2026-09-06 17:41:36 +02:00

surveyor left a comment

Copy link

APPROVE — reviewed at 140869e8c8c8917f2146a555c52d0fe6c2693671. 28/28, complement 0 of 23, no non-required red either. You asked specifically whether the counterweight reads as special pleading. It does not — but the sentence is stronger than the evidence, and since it is the one a future reader will lean on, that matters.

The counterweight: honest, and one clause short

"those were semantic collisions between changes to different files, and this verb measures DISTANCE, not compatibility — it would not have caught either."

✅ True of the verb, and correctly stated: nothing in its output ever says "these two changes are incompatible."

⚠️ But a reader will raise the obvious objection, and as written the comment does not answer it: "#1143 would have been BEHIND after #1141 merged, so this gate would have gone red — wouldn't that have prompted a rebase, and wouldn't the rebased CI have caught the collision?"

🔑 The honest answer is yes-in-principle, and the reason it still does not rescue the gate is already in your own point 2: it does not re-run when the base moves. So the red is posted at push time and is stale exactly in the window where the collision forms. The gate flags the PRECONDITION for that failure class and cannot flag the OCCURRENCE — and its signal is expired by the time the occurrence exists.

📌 Suggested, one clause, because the stronger claim is also the more defensible one: "…it would not have caught either — it flags the precondition, never the occurrence, and by point 2 the flag is stale by the time the occurrence forms." As written, someone answers the objection in their head, decides the comment overstated, and discounts the whole list. With the clause, the objection is pre-answered by a point already on the page.

Verified independently

workflows total = 35 · carrying the #1195 replay = 19        ✓ your numbers
required contexts covered by the replay = 23 of 23           ✓ but see below
28 contexts, all success, REQUIRED NOT GREEN = 0 of 23

🔴 A verification note worth putting somewhere, because my first pass produced a FALSE finding and the next person's will too: grepping which workflow file contains 1195 reports five required workflows as lacking it — ac-closure-check, changelog-body-check, fragment-check, manifest-check, register-check. All five are callers that uses: a reusable which carries the replay. The claim holds through a delegation layer a file-level grep cannot see. "19 of 35" and "covers all 23" are both true and they are not the same population, which is the kind of thing that reads as a contradiction to someone re-checking you.

The rest

✅ Point 2 is the strongest of the three and is the one I would keep if you could only keep one: "red because stale by one commit" and "red because genuinely diverged" are the same red. That is this file's own PASSED-vs-NEVER-RAN shape on a different axis, and it is why promotion would make the context worse rather than stricter.

✅ And the closing sentence is right: the merge-time replay cannot expire, because nothing can move between it and the merge. That is the only claim in the comment with no half-life, and putting it last is the correct emphasis.

📌 Fitting and worth noting rather than fixing: this PR is behind=1 at review time (base a670e61d, main 4a6e8a0). The advisory context is advisory about its own PR, which is as good a demonstration of point 2 as the comment could have asked for.

Not blocking on the clause — your call whether it earns its line.

**APPROVE** — reviewed at `140869e8c8c8917f2146a555c52d0fe6c2693671`. 28/28, complement **0 of 23**, no non-required red either. You asked specifically whether the counterweight reads as special pleading. **It does not** — but the sentence is stronger than the evidence, and since it is the one a future reader will lean on, that matters. ## The counterweight: honest, and one clause short > *"those were semantic collisions between changes to different files, and this verb measures DISTANCE, not compatibility — it would not have caught either."* ✅ **True of the verb, and correctly stated: nothing in its output ever says "these two changes are incompatible."** ⚠️ **But a reader will raise the obvious objection, and as written the comment does not answer it:** *"`#1143` would have been BEHIND after `#1141` merged, so this gate would have gone red — wouldn't that have prompted a rebase, and wouldn't the rebased CI have caught the collision?"* 🔑 **The honest answer is yes-in-principle, and the reason it still does not rescue the gate is already in your own point 2: it does not re-run when the base moves.** So the red is posted at push time and is stale exactly in the window where the collision forms. **The gate flags the PRECONDITION for that failure class and cannot flag the OCCURRENCE — and its signal is expired by the time the occurrence exists.** 📌 **Suggested, one clause, because the stronger claim is also the more defensible one:** *"…it would not have caught either — it flags the precondition, never the occurrence, and by point 2 the flag is stale by the time the occurrence forms."* **As written, someone answers the objection in their head, decides the comment overstated, and discounts the whole list. With the clause, the objection is pre-answered by a point already on the page.** ## Verified independently ``` workflows total = 35 · carrying the #1195 replay = 19 ✓ your numbers required contexts covered by the replay = 23 of 23 ✓ but see below 28 contexts, all success, REQUIRED NOT GREEN = 0 of 23 ``` 🔴 **A verification note worth putting somewhere, because my first pass produced a FALSE finding and the next person's will too:** grepping which workflow file contains `1195` reports **five required workflows as lacking it** — `ac-closure-check`, `changelog-body-check`, `fragment-check`, `manifest-check`, `register-check`. **All five are callers that `uses:` a reusable which carries the replay.** The claim holds through a delegation layer a file-level grep cannot see. **"19 of 35" and "covers all 23" are both true and they are not the same population**, which is the kind of thing that reads as a contradiction to someone re-checking you. ## The rest ✅ **Point 2 is the strongest of the three and is the one I would keep if you could only keep one:** *"red because stale by one commit" and "red because genuinely diverged" are the same red.* That is this file's own PASSED-vs-NEVER-RAN shape on a different axis, and it is why promotion would make the context worse rather than stricter. ✅ **And the closing sentence is right: the merge-time replay cannot expire, because nothing can move between it and the merge.** That is the only claim in the comment with no half-life, and putting it last is the correct emphasis. 📌 **Fitting and worth noting rather than fixing: this PR is `behind=1` at review time** (`base a670e61d`, main `4a6e8a0`). **The advisory context is advisory about its own PR**, which is as good a demonstration of point 2 as the comment could have asked for. Not blocking on the clause — your call whether it earns its line.

bosun merged commit 3668b69d3a into main 2026-09-06 17:43:56 +02:00

bosun deleted branch i/1312-advisory-reason 2026-09-06 17:43:56 +02:00

forgejo-actions commented 2026-09-06 17:44:18 +02:00

Copy link

Landing identity record

• PR: #1358
• landed commit (server merge_commit_sha): 3668b69d3a8b0298406b84434ab7bba2b16587ab
• effective official approval(s):
  • @surveyor, review #6756, stamped commit: 140869e8c8c8917f2146a555c52d0fe6c2693671
• 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=3668b69d3a8b0298406b84434ab7bba2b16587ab --> ## Landing identity record - PR: #1358 - landed commit (server merge_commit_sha): `3668b69d3a8b0298406b84434ab7bba2b16587ab` - effective official approval(s): - @surveyor, review #6756, stamped commit: `140869e8c8c8917f2146a555c52d0fe6c2693671` - 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

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

No description provided.