docs(upgrade): changelog-body check 5 became a failure at v0.48.2 without an Upgrade note, and pr-gates now grades it on every PR #1551

New issue

Open

opened 2026-10-05 21:39:41 +02:00 by claude · 1 comment

claude commented

2026-10-05 21:39:41 +02:00

Member

Measured

Measured on 2026-10-05 while migrating frankenbit/purser (purser#63) from @v0.36.0 to reusable-pr-gates.yml@v0.66.0, using rt built from v0.66.0 (b1a9578) on purser's branch:

purser's already-released [0.4.0] section fails the changelog-body gate: FAIL: check 5 (style): mixed bullet+prose in section(s): Added (bullets=2 prose=8).
At v0.36.0, check 5 was a warning. It became a failure at v0.48.2 (commit 6d218b0, #931). The v0.48.2 changelog has no ### Upgrade note for it.
The old reusable-changelog-body-check.yml wrapper ran only on PRs that touched CHANGELOG.md. reusable-pr-gates.yml follows ADR-0013's wiring rule, with no paths: filter, so changelog_body: 'on' now grades the whole CHANGELOG on EVERY PR. An adopter with any old failing section goes red on every PR the moment it migrates.

purser is fixing its own CHANGELOG in its migration PR, at the operator's decision. This issue covers the toolkit side.

Why it matters

Two behaviour changes reach changelog_body adopters without a word in any Upgrade section. Only purser runs that gate today, but the migration guide (#1530) tells adopters to switch on the gates they already ran.

Acceptance criteria

The toolkit's adopter docs (integration guide, and C3 for pr-gates' changelog_body input) state both changes:
- check 5 has been a failure since v0.48.2;
- under pr-gates, changelog_body grades every PR, not only PRs that change CHANGELOG.md.
A decision, recorded with its reasons: should pr-gates' changelog_body grade only the sections a PR changes (the newest or unreleased section), or the whole file? This needs a decision tree (AGENTS.md section 7), because a whole-file grade turns old released text into a standing red.
Whether the v0.48.2 omission calls for a retroactive Upgrade line, or a note in the next release's Upgrade section.

## Measured Measured on 2026-10-05 while migrating frankenbit/purser (purser#63) from `@v0.36.0` to `reusable-pr-gates.yml@v0.66.0`, using `rt` built from v0.66.0 (`b1a9578`) on purser's branch: - **purser's already-released `[0.4.0]` section fails the changelog-body gate:** `FAIL: check 5 (style): mixed bullet+prose in section(s): Added (bullets=2 prose=8)`. - **At v0.36.0, check 5 was a warning. It became a failure at v0.48.2** (commit `6d218b0`, #931). The v0.48.2 changelog has no `### Upgrade` note for it. - **The old `reusable-changelog-body-check.yml` wrapper ran only on PRs that touched `CHANGELOG.md`.** `reusable-pr-gates.yml` follows ADR-0013's wiring rule, with no `paths:` filter, so `changelog_body: 'on'` now grades the whole CHANGELOG on EVERY PR. An adopter with any old failing section goes red on every PR the moment it migrates. purser is fixing its own CHANGELOG in its migration PR, at the operator's decision. This issue covers the toolkit side. ## Why it matters Two behaviour changes reach `changelog_body` adopters without a word in any Upgrade section. Only purser runs that gate today, but the migration guide (#1530) tells adopters to switch on the gates they already ran. ## Acceptance criteria - [ ] The toolkit's adopter docs (integration guide, and C3 for pr-gates' `changelog_body` input) state both changes: - check 5 has been a failure since v0.48.2; - under pr-gates, `changelog_body` grades every PR, not only PRs that change CHANGELOG.md. - [ ] A decision, recorded with its reasons: should pr-gates' changelog_body grade only the sections a PR changes (the newest or unreleased section), or the whole file? This needs a decision tree (AGENTS.md section 7), because a whole-file grade turns old released text into a standing red. - [ ] Whether the v0.48.2 omission calls for a retroactive Upgrade line, or a note in the next release's Upgrade section.

claude added the

labels

2026-10-05 21:39:41 +02:00

claude referenced this issue from a commit

2026-10-05 21:46:25 +02:00

docs(changelog): give #18's entry in the 0.4.0 section its bullet header

claude referenced this issue from frankenbit/purser

2026-10-05 21:46:51 +02:00

chore(ci): run the release-toolkit PR gates from one pr.yml at v0.66.0 #64

claude referenced this issue from frankenbit/purser

2026-10-05 21:46:51 +02:00

chore(ci): run the release-toolkit PR gates from one pr.yml at v0.66.0 #64

claude commented

2026-10-05 21:47:03 +02:00

Author

Member

A related finding from the same purser migration (purser PR #64): fragment-check's WARN text overstates what happens at cut time.

On a PR, a pre-existing fragment that breaks a density limit only warns (#735). The message then says such fragments "still fail at cut time".
Measured, that does not hold for a sentence in the fragment body.
- rt prep --dry-run from v0.66.0, on purser's pre-fix tree eb36faf, has changelog.d/61.fixed.md carrying a sentence over the limit in its body.
- The cut-time compose-verify mirror still reported "Cut-time changelog gates - clean".
- Since v0.48.0 (#854), a fragment contributes only its summary line to the composed section, so the body never reaches the cut-time density check.

So the WARN should say WHICH part of a fragment can still fail at cut time (the summary line), or stop claiming a cut-time failure for body text. Add this to the docs criterion above, or split it out if it grows.

A related finding from the same purser migration (purser PR #64): fragment-check's WARN text overstates what happens at cut time. - **On a PR, a pre-existing fragment that breaks a density limit only warns** (#735). The message then says such fragments "still fail at cut time". - **Measured, that does not hold for a sentence in the fragment body.** - `rt prep --dry-run` from v0.66.0, on purser's pre-fix tree `eb36faf`, has `changelog.d/61.fixed.md` carrying a sentence over the limit in its body. - The cut-time compose-verify mirror still reported "Cut-time changelog gates - clean". - Since v0.48.0 (#854), a fragment contributes only its summary line to the composed section, so the body never reaches the cut-time density check. So the WARN should say WHICH part of a fragment can still fail at cut time (the summary line), or stop claiming a cut-time failure for body text. Add this to the docs criterion above, or split it out if it grows.

claude referenced this issue

2026-10-06 00:14:14 +02:00

chore(workflows)!: remove the six single-gate reusables, their wrappers and twins after reusable-pr-gates.yml lands, and cut the next minor #1542