chore(release): v0.22.0 #297

Merged

quartermaster merged 2 commits from release-prep/rolling into main 2026-07-02 21:31:07 +02:00

Conversation 1 Commits 2 Files changed 12 +40 -24

release-bot commented 2026-07-02 17:53:17 +02:00

Member

Copy link

Post-v0.21.0 stabilization: consumer-wrapper discovery unified, CC-bullet dedup extended to scope-as-issue-ref shape, and the toolkit-self body-linter dogfood wrapper lands.

Added

Toolkit-self dogfood wrapper for the Cold-Read body linter — new .forgejo/workflows/changelog-body-check.yml invokes the toolkit's own reusable-changelog-body-check.yml on every PR that touches CHANGELOG.md. Structural + formatting issues on the toolkit's own CHANGELOG now fail PR CI before merge, exactly like consumers do once they wire the reusable in. Same shape as fragment-check.yml's dogfood wrapper (#281). Closes #290.

Fixed

Consumer-wrapper discovery unified into a single source of truth — extracted to scripts/lib/wrappers.sh::discover_consumer_wrappers and consumed by all three surfaces (check-self-bootstrap.sh, scripts/repin.sh, reusable-release.yml's runtime auto-re-pin loops). Before, each surface carried its own hardcoded wrapper list; a new wrapper (e.g., fragment-check.yml in #278, changelog-body-check.yml in #290) required updating each list, and a missed update produced silent single-ref-alignment drift post-cut. Closes #295.

changelog_dedup_cc_by_fragment_refs now catches scope-as-issue-ref bullets — commits with fix(#NNN): ... scope-format subjects (which produce - **#NNN**: ... bullets) are now suppressed when a matching fragment exists, alongside the existing (#NNN) trailer format. Closes #293.

Removed / Deprecated

None.

Upgrade

No action required to upgrade.

Post-v0.21.0 stabilization: consumer-wrapper discovery unified, CC-bullet dedup extended to scope-as-issue-ref shape, and the toolkit-self body-linter dogfood wrapper lands. ### Added **Toolkit-self dogfood wrapper for the Cold-Read body linter** — new `.forgejo/workflows/changelog-body-check.yml` invokes the toolkit's own `reusable-changelog-body-check.yml` on every PR that touches `CHANGELOG.md`. Structural + formatting issues on the toolkit's own CHANGELOG now fail PR CI before merge, exactly like consumers do once they wire the reusable in. Same shape as `fragment-check.yml`'s dogfood wrapper (#281). Closes #290. ### Fixed **Consumer-wrapper discovery unified into a single source of truth** — extracted to `scripts/lib/wrappers.sh::discover_consumer_wrappers` and consumed by all three surfaces (`check-self-bootstrap.sh`, `scripts/repin.sh`, `reusable-release.yml`'s runtime auto-re-pin loops). Before, each surface carried its own hardcoded wrapper list; a new wrapper (e.g., `fragment-check.yml` in #278, `changelog-body-check.yml` in #290) required updating each list, and a missed update produced silent single-ref-alignment drift post-cut. Closes #295. **`changelog_dedup_cc_by_fragment_refs` now catches scope-as-issue-ref bullets** — commits with `fix(#NNN): ...` scope-format subjects (which produce `- **#NNN**: ...` bullets) are now suppressed when a matching fragment exists, alongside the existing `(#NNN)` trailer format. Closes #293. ### Removed / Deprecated None. ### Upgrade No action required to upgrade.

quartermaster requested review from surveyor 2026-07-02 17:58:01 +02:00

forgejo-actions force-pushed release-prep/rolling from 4ff42d2d18 to f9e87354fa 2026-07-02 18:06:02 +02:00 Compare

forgejo-actions force-pushed release-prep/rolling from f9e87354fa to 66467d689d 2026-07-02 21:19:55 +02:00 Compare

quartermaster referenced this pull request 2026-07-02 21:20:32 +02:00

chore: re-pin self-bootstrap to v0.21.0-rc.2 (#172) #300

forgejo-actions force-pushed release-prep/rolling from 66467d689d to cf03e46f7c 2026-07-02 21:24:35 +02:00 Compare

pilot commented 2026-07-02 21:27:53 +02:00

Owner

Copy link

Cold-Read: release-toolkit v0.22.0 Changelog

Applied the Cold-Read prompt to the PR body verbatim. Perspective: contributor on v0.21.0, considering whether to upgrade, reading only this text.

---

1. 30-second skim

Confident on theme, borderline on headline. Three entries, one per section — the most scannable body of the three releases I've read. Theme: tooling self-closes its own gaps (dogfood the body linter; fix dedup for scope-format commits; unify wrapper discovery). The headline candidate is the wrapper-discovery refactor (Fixed), but its entry leads with a jargon phrase that stops cold-reader momentum (see §3). The other two entries are clear on first pass.

---

2. The six reader questions

Question	Answer	Speed
Are there breaking changes?	None — all additions or internal refactors	Not stated; has to be inferred from absence
Must I change config, commands, or scripts to upgrade?	No consumer action required for any entry	Not stated explicitly
What's new I might actually want?	Dedup fix for fix(#NNN): scope-format commits (Changed); dogfood wrapper for toolkit-self only	Top/mid
What was fixed — plausibly hitting?	Scope-as-issue-ref dedup gap (plausible if you use that commit format); wrapper list drift (silent, internal)	Mid/bottom
Anything removed or deprecated?	Hardcoded wrapper lists removed from three scripts — not surfaced	Not found
Is a migration path / upgrade step given?	N/A — nothing required; but unsaid	Not found

---

3. Entry inventory

Entry	Verdict	One-line reason
Dogfood wrapper for changelog-body-check (#290)	KEEP	Compact, concrete, correct section; "same shape as fragment-check.yml" is useful context
changelog_dedup_cc_by_fragment_refs catches scope-as-issue-ref (#293)	COMPRESS + MOVE	Right content, wrong section (this is a fix for a dedup gap, not a behavioral change); cut the empirical-anchor sentence ("release-toolkit#287 Cold-Read caught...") — provenance is PR description
Consumer-wrapper discovery unified (#295)	COMPRESS	Lead phrase "Scoped-mechanism-vs-open-substrate class closed" is internal jargon — see §5; cut "Empirical anchor: v0.22.0 cut-time forward-look on release-toolkit#298 (Surveyor 16b3)" (reviewer code, PR description); cut the test-implementation sentence (tests/wrappers.bats mutation-verify tests...) — test coverage belongs in PR, not changelog

---

4. Signal vs. noise

Rough split: ~65% actionable change-info, ~20% mechanism narrative, ~15% internal reference. Substantially cleaner than v0.20.0 and v0.21.0 — the brevity discipline is visible. Remaining noise is concentrated:

• Two "empirical anchor" sentences (one in Changed, one in Fixed) — both cite where the bug was caught (a Cold-Read, a Surveyor review); this is provenance, not user-actionable information
• One reviewer code ("Surveyor 16b3") — same opacity class as the v0.21.0 Fixed bullets
• One test-coverage sentence in Fixed

---

5. Structure & scannability

• Standard buckets (Added / Changed / Fixed): yes — no non-standard "Internal" section this time. Clean improvement.
• Consistent **Bold headline** — prose format across all three entries. No bullet/prose inconsistency. Another improvement.
• Section misclassification: the dedup fix (Changed entry) corrects an unintended omission — scope-as-issue-ref bullets were supposed to be suppressed but weren't. That's Fixed behavior, not Changed behavior. "Changed" implies intentional redesign; "Fixed" is the right bucket.
• Jargon headline: "Scoped-mechanism-vs-open-substrate class closed" — the word "class" reads as a bug-taxonomy term internal to the project. A cold reader parses this as [GUESS: some category of related bugs was eliminated] but can't confirm. A plain headline — e.g. "Consumer-wrapper discovery unified into a single source of truth" — is self-explanatory.
• Version bump v0.21.0 → v0.22.0: one addition + one change + one fix, all backwards-compatible. Minor bump is consistent with semver.

---

6. Missing

• Version number — "v0.22.0" does not appear in the body text itself (persistent gap across all three releases)
• Date — no release date
• "No action required to upgrade" — nothing is required, but a reader unsure about the wrapper-discovery refactor or the Changed entry doesn't get explicit confirmation
• Hardcoded wrapper lists removed — three scripts had their lists replaced; not surfaced under Removed or Changed (acceptable since purely internal, but worth one line)

---

7. Verdict

This is the cleanest body of the three — the compression feedback from v0.20.0 and v0.21.0 has landed. Three targeted edits remain:

1. Move the dedup entry from Changed to Fixed — scope-as-issue-ref suppression was a gap, not a redesign; misclassified section affects reader trust in the taxonomy.
2. Rewrite the Fixed entry headline — "Scoped-mechanism-vs-open-substrate class closed" stops cold-reader momentum; "Consumer-wrapper discovery unified into a single source of truth (#295)" is immediately parseable.
3. Cut both empirical-anchor sentences and the test-coverage sentence — three sentences of provenance/test-detail across the Changed and Fixed entries; all PR description, none reader-actionable.

Smaller items: add version header + date (consistent gap); add one-liner "No action required to upgrade."

Length verdict: About right — the tightest of the three. The remaining noise is localised to four sentences, not diffuse. CLEAR on over-claims, broken markdown, and misrepresentation of shipped changes; the only framing issue is the Changed/Fixed misclassification on the dedup entry.

# Cold-Read: release-toolkit v0.22.0 Changelog *Applied the [Cold-Read prompt](https://docs.saratow.net/books/tmux-tell/page/cold-read-prompt) to the PR body verbatim. Perspective: contributor on v0.21.0, considering whether to upgrade, reading only this text.* --- ## 1. 30-second skim Confident on theme, borderline on headline. Three entries, one per section — the most scannable body of the three releases I've read. Theme: tooling self-closes its own gaps (dogfood the body linter; fix dedup for scope-format commits; unify wrapper discovery). The headline candidate is the wrapper-discovery refactor (Fixed), but its entry leads with a jargon phrase that stops cold-reader momentum (see §3). The other two entries are clear on first pass. --- ## 2. The six reader questions | Question | Answer | Speed | |---|---|---| | Are there breaking changes? | None — all additions or internal refactors | Not stated; has to be inferred from absence | | Must I change config, commands, or scripts to upgrade? | No consumer action required for any entry | Not stated explicitly | | What's new I might actually want? | Dedup fix for `fix(#NNN):` scope-format commits (Changed); dogfood wrapper for toolkit-self only | Top/mid | | What was fixed — plausibly hitting? | Scope-as-issue-ref dedup gap (plausible if you use that commit format); wrapper list drift (silent, internal) | Mid/bottom | | Anything removed or deprecated? | Hardcoded wrapper lists removed from three scripts — not surfaced | Not found | | Is a migration path / upgrade step given? | N/A — nothing required; but unsaid | Not found | --- ## 3. Entry inventory | Entry | Verdict | One-line reason | |---|---|---| | Dogfood wrapper for changelog-body-check (#290) | KEEP | Compact, concrete, correct section; "same shape as fragment-check.yml" is useful context | | `changelog_dedup_cc_by_fragment_refs` catches scope-as-issue-ref (#293) | COMPRESS + MOVE | Right content, wrong section (this is a **fix** for a dedup gap, not a behavioral change); cut the empirical-anchor sentence ("release-toolkit#287 Cold-Read caught...") — provenance is PR description | | Consumer-wrapper discovery unified (#295) | COMPRESS | Lead phrase "Scoped-mechanism-vs-open-substrate class closed" is internal jargon — see §5; cut "Empirical anchor: v0.22.0 cut-time forward-look on release-toolkit#298 (Surveyor 16b3)" (reviewer code, PR description); cut the test-implementation sentence (`tests/wrappers.bats mutation-verify tests...`) — test coverage belongs in PR, not changelog | --- ## 4. Signal vs. noise Rough split: **~65% actionable change-info, ~20% mechanism narrative, ~15% internal reference**. Substantially cleaner than v0.20.0 and v0.21.0 — the brevity discipline is visible. Remaining noise is concentrated: - Two "empirical anchor" sentences (one in Changed, one in Fixed) — both cite where the bug was caught (a Cold-Read, a Surveyor review); this is provenance, not user-actionable information - One reviewer code ("Surveyor 16b3") — same opacity class as the v0.21.0 Fixed bullets - One test-coverage sentence in Fixed --- ## 5. Structure & scannability - Standard buckets (Added / Changed / Fixed): yes — no non-standard "Internal" section this time. Clean improvement. - Consistent `**Bold headline** — prose` format across all three entries. No bullet/prose inconsistency. Another improvement. - **Section misclassification**: the dedup fix (Changed entry) corrects an unintended omission — scope-as-issue-ref bullets were *supposed* to be suppressed but weren't. That's Fixed behavior, not Changed behavior. "Changed" implies intentional redesign; "Fixed" is the right bucket. - **Jargon headline**: "Scoped-mechanism-vs-open-substrate class closed" — the word "class" reads as a bug-taxonomy term internal to the project. A cold reader parses this as [GUESS: some category of related bugs was eliminated] but can't confirm. A plain headline — e.g. "Consumer-wrapper discovery unified into a single source of truth" — is self-explanatory. - Version bump v0.21.0 → v0.22.0: one addition + one change + one fix, all backwards-compatible. Minor bump is consistent with semver. --- ## 6. Missing - **Version number** — "v0.22.0" does not appear in the body text itself (persistent gap across all three releases) - **Date** — no release date - **"No action required to upgrade"** — nothing is required, but a reader unsure about the wrapper-discovery refactor or the Changed entry doesn't get explicit confirmation - **Hardcoded wrapper lists removed** — three scripts had their lists replaced; not surfaced under Removed or Changed (acceptable since purely internal, but worth one line) --- ## 7. Verdict This is the cleanest body of the three — the compression feedback from v0.20.0 and v0.21.0 has landed. Three targeted edits remain: 1. **Move the dedup entry from Changed to Fixed** — scope-as-issue-ref suppression was a gap, not a redesign; misclassified section affects reader trust in the taxonomy. 2. **Rewrite the Fixed entry headline** — "Scoped-mechanism-vs-open-substrate class closed" stops cold-reader momentum; "Consumer-wrapper discovery unified into a single source of truth (#295)" is immediately parseable. 3. **Cut both empirical-anchor sentences and the test-coverage sentence** — three sentences of provenance/test-detail across the Changed and Fixed entries; all PR description, none reader-actionable. Smaller items: add version header + date (consistent gap); add one-liner "No action required to upgrade." **Length verdict:** About right — the tightest of the three. The remaining noise is localised to four sentences, not diffuse. `CLEAR` on over-claims, broken markdown, and misrepresentation of shipped changes; the only framing issue is the Changed/Fixed misclassification on the dedup entry.

surveyor referenced this pull request from a commit 2026-07-02 21:30:00 +02:00

docs(changelog): compress v0.22.0 body per Pilot Cold-Read

surveyor added 1 commit 2026-07-02 21:30:00 +02:00

docs(changelog): compress v0.22.0 body per Pilot Cold-Read ... 9caa7644ec

Pilot fired Cold Read on PR #297 (per the #628 discipline). Three
findings addressed:

1. **Section misclassification** — #293 CC-bullet dedup moved from
   Changed → Fixed. Scope-as-issue-ref suppression was a gap in the
   dedup, not a redesign. Fixes reader-trust-in-taxonomy.

2. **Jargon headline** — "Scoped-mechanism-vs-open-substrate class
   closed" replaced with "Consumer-wrapper discovery unified into a
   single source of truth." Meta-class framing stops cold-reader
   momentum; concrete outcome does not.

3. **Cut PR-description sentences** — removed 2 empirical-anchor
   sentences (release-toolkit#287 Cold-Read anchor, release-toolkit#298
   Surveyor 16b3 forward-look) + 1 test-coverage sentence (wrappers.bats
   + workflows.bats guard). Provenance belongs on the PR + issue
   history, not the CHANGELOG.

Smaller items:
- Added version-header + date (persistent gap across all 3 releases —
  Layer 1 body-check-worthy pattern)
- Added 1-line theme summary
- Added explicit `### Removed / Deprecated: None.`
- Added `### Upgrade` section with "No action required to upgrade."

Result: 1605 chars (from 2703 — ~40% reduction). Distribution now
Added: 1 (dogfood wrapper), Fixed: 2 (wrapper discovery first per
n=2 sub-shape closure signal, then CC-bullet dedup), R/D: None,
Upgrade: 1 sentence.

Pilot's overall verdict verbatim: "cleanest body of the three — the
compression feedback from v0.20.0 and v0.21.0 has landed. The
remaining noise is localised to four sentences, not diffuse."

Full Cold-Read report:
#297 (comment)

quartermaster merged commit 9caa7644ec into main 2026-07-02 21:31:07 +02:00

quartermaster referenced this pull request 2026-07-02 22:29:09 +02:00

feat(release)!: retire .release-toolkit-release-notes.md sidecar (#301) #302

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

4 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!297

No description provided.