frankenbit/release-toolkit
frankenbit/release-toolkit
15
1
Fork 0
Code Issues 11 Pull requests Projects Releases 106 Packages 1 Wiki Activity Actions

chore(release): v0.23.0 #303

Merged
quartermaster merged 2 commits from release-prep/rolling into main 2026-07-02 23:41:01 +02:00
Conversation 1 Commits 2 Files changed 9 +32 -15
release-bot commented 2026-07-02 22:36:53 +02:00
Member
Copy link

Post-v0.22.0 correctness fix: retire the release-notes sidecar so edits to CHANGELOG.md actually reach the Forgejo release page.

Removed

BREAKING: .release-toolkit-release-notes.md sidecar retired — CHANGELOG.md is the single source of truth for the release-body content. The v0.5.0-introduced sidecar (fed by fragment summary: frontmatter) was preferred by draft-release.sh over the CHANGELOG section, so edits to CHANGELOG.md were silently ignored on the release page. draft-release.sh now always reads the CHANGELOG section. release-prep.sh no longer writes a sidecar and deletes any legacy committed sidecar on the first post-#301 cut so the file stops shipping stale content. summary: frontmatter on fragments becomes inert (safe to leave or strip). Closes #301.

Upgrade

If your repo has committed a .release-toolkit-release-notes.md file from a pre-v0.23.0 cut, delete it:

git rm .release-toolkit-release-notes.md && git commit -m "chore: drop retired sidecar per release-toolkit#301"

draft-release.sh ignores the file post-v0.23.0, so leaving it in place is a no-op (not an error). Nothing else needed to upgrade.

Post-v0.22.0 correctness fix: retire the release-notes sidecar so edits to `CHANGELOG.md` actually reach the Forgejo release page. ### Removed **BREAKING: `.release-toolkit-release-notes.md` sidecar retired — CHANGELOG.md is the single source of truth for the release-body content.** The v0.5.0-introduced sidecar (fed by fragment `summary:` frontmatter) was preferred by `draft-release.sh` over the CHANGELOG section, so edits to `CHANGELOG.md` were silently ignored on the release page. `draft-release.sh` now always reads the CHANGELOG section. `release-prep.sh` no longer writes a sidecar and deletes any legacy committed sidecar on the first post-#301 cut so the file stops shipping stale content. `summary:` frontmatter on fragments becomes inert (safe to leave or strip). Closes #301. ### Upgrade If your repo has committed a `.release-toolkit-release-notes.md` file from a pre-v0.23.0 cut, delete it: ```bash git rm .release-toolkit-release-notes.md && git commit -m "chore: drop retired sidecar per release-toolkit#301" ``` `draft-release.sh` ignores the file post-v0.23.0, so leaving it in place is a no-op (not an error). Nothing else needed to upgrade.
chore(release): prepare v0.23.0
Some checks failed
changelog-body-check / changelog body Cold-Read linter (pull_request) Successful in 4s
Details
changelog-body-check / check (pull_request) Successful in 0s
Details
check-self-bootstrap / check (pull_request) Failing after 3s
Details
fragment-check / changelog fragment-kind (pull_request) Successful in 4s
Details
fragment-check / check (pull_request) Successful in 0s
Details
manifest-check / manifest-vs-tag consistency (pull_request) Successful in 5s
Details
manifest-check / check (pull_request) Successful in 0s
Details
de7cff2c04 
Generated by release-toolkit release-prep.sh.

Tracker: frankenbit/release-toolkit#1
pilot commented 2026-07-02 23:39:01 +02:00
Owner
Copy link

Cold-Read: release-toolkit v0.23.0 Changelog

Applied the Cold-Read prompt to the v0.23.0 CHANGELOG.md entry verbatim. Perspective: contributor on v0.22.0, considering whether to upgrade, reading only this text.

1. 30-second skim

Confident on what changed; not confident on what I need to do. The BREAKING label is prominent and the retirement is clear. But the reader question "must I change anything to upgrade?" requires reading a full prose paragraph to extract the answer. For a BREAKING entry with a real consumer action, that's the wrong shape.

2. The six reader questions

Question Answer Speed
Are there breaking changes? Yes -- BREAKING is in the headline in bold Top
Must I change config, commands, or scripts to upgrade? Yes -- git rm .release-toolkit-release-notes.md if you have a committed sidecar; summary: frontmatter becomes inert Mid (buried in prose, no dedicated section)
What's new that I might actually want? N/A -- this is a retirement --
What was fixed? N/A -- no Fixed section --
Anything removed or deprecated? Yes -- sidecar retired, summary: frontmatter inert Not found as a dedicated section
Is a migration path / upgrade step given? Partially -- git rm is mentioned in prose but there is no ### Upgrade section Not found as a unit

3. Entry inventory

One entry:

Entry Verdict One-line reason
Sidecar retirement (BREAKING) COMPRESS + RESTRUCTURE Content is accurate and well-scoped; the consumer action (git rm) is buried mid-paragraph; "Cold-Read compression edits" is insider framing (see below); missing sections are the main issue, not prose length

4. Signal vs. noise

Rough split: ~70% actionable change-info, ~30% mechanism narrative. This is the tightest entry of the series -- the "why" (silently discarding edits) is correctly brief. One phrase worth flagging:

"was silently discarding Cold-Read compression edits that only touched CHANGELOG.md"

"Cold-Read compression edits" is insider framing. An adopter who doesn't know the Cold-Read discipline reads this as [GUESS: some kind of editorial process?]. The mechanism description "edits to CHANGELOG.md were silently ignored when the sidecar existed" is self-contained and clearer. The Cold-Read provenance belongs in the PR, not the changelog.

5. Structure & scannability

  • Version header + date: present (## [v0.23.0] - 2026-07-02). Good.
  • Theme-summary line: absent. v0.21.0 and v0.22.0 both carry a one-liner between the version header and the first section ("Post-v0.21.0 stabilization: ...", "Changelog tooling + release automation: ..."). v0.23.0 goes straight to ### Changed. The theme is easy to state: "Sidecar retirement: CHANGELOG.md is now the single source of truth for release-body content."
  • Section classification: the sidecar retirement is in ### Changed. It is more precisely a removal -- the sidecar file is no longer generated, summary: frontmatter is inert. ### Removed would be the standard bucket. The BREAKING label is correct and prominent; the bucket is wrong.
  • ### Removed / Deprecated section: absent. v0.22.0 established the precedent (None. when empty). This entry has non-trivial removals (sidecar file, effective inert-ing of frontmatter); the section should be present and populated, not omitted.
  • ### Upgrade section: absent. v0.22.0 established the precedent. This is the sharpest gap: there IS a consumer action (git rm .release-toolkit-release-notes.md for legacy sidecar holders), but a reader scanning for the Upgrade section to answer "what must I do?" finds nothing. The action is in the prose, not where the reader looks.

6. Missing

  • Theme-summary line between version header and first section
  • ### Removed / Deprecated section -- the sidecar feature and summary: frontmatter effectiveness are both removed; they belong here, not under Changed
  • ### Upgrade section -- the git rm .release-toolkit-release-notes.md consumer action needs to be explicit and scannable, not embedded in prose
  • No ### Added or ### Fixed sections -- acceptable if genuinely empty, but worth confirming with None. per the standard (the body-linter checks for this)

7. Verdict

Content quality is good -- the entry is accurate, the BREAKING label is prominent and warranted, and the prose is appropriately tight. The issues are structural, not prose-density:

  1. Add ### Upgrade section with the git rm action explicit. This is the highest-leverage fix: a BREAKING entry with a consumer action must answer "what do I do?" without requiring a paragraph read.
  2. Move sidecar retirement to ### Removed (or add a ### Removed section that calls it out explicitly) -- summary: frontmatter becoming inert is a removal, not a change.
  3. Add theme-summary line between the version header and the first section -- consistent with v0.21.0/v0.22.0 precedent.
  4. Cut "Cold-Read compression edits" -- replace with "edits to CHANGELOG.md were silently ignored when the sidecar existed."

Minor: confirm ### Added / ### Fixed are genuinely empty with None. entries (the body-linter will flag their absence).

Length verdict: About right. One entry for a one-change release is correct. The restructuring above (Upgrade section + Removed section + theme line) adds ~4 lines and significantly improves the answer to the single most important reader question for a BREAKING entry.

# Cold-Read: release-toolkit v0.23.0 Changelog *Applied the [Cold-Read prompt](https://docs.saratow.net/books/tmux-tell/page/cold-read-prompt) to the v0.23.0 CHANGELOG.md entry verbatim. Perspective: contributor on v0.22.0, considering whether to upgrade, reading only this text.* --- ## 1. 30-second skim Confident on what changed; not confident on what I need to do. The BREAKING label is prominent and the retirement is clear. But the reader question "must I change anything to upgrade?" requires reading a full prose paragraph to extract the answer. For a BREAKING entry with a real consumer action, that's the wrong shape. --- ## 2. The six reader questions | Question | Answer | Speed | |---|---|---| | Are there breaking changes? | Yes -- `BREAKING` is in the headline in bold | Top | | Must I change config, commands, or scripts to upgrade? | Yes -- `git rm .release-toolkit-release-notes.md` if you have a committed sidecar; `summary:` frontmatter becomes inert | Mid (buried in prose, no dedicated section) | | What's new that I might actually want? | N/A -- this is a retirement | -- | | What was fixed? | N/A -- no Fixed section | -- | | Anything removed or deprecated? | Yes -- sidecar retired, `summary:` frontmatter inert | Not found as a dedicated section | | Is a migration path / upgrade step given? | Partially -- `git rm` is mentioned in prose but there is no `### Upgrade` section | Not found as a unit | --- ## 3. Entry inventory One entry: | Entry | Verdict | One-line reason | |---|---|---| | Sidecar retirement (BREAKING) | COMPRESS + RESTRUCTURE | Content is accurate and well-scoped; the consumer action (`git rm`) is buried mid-paragraph; "Cold-Read compression edits" is insider framing (see below); missing sections are the main issue, not prose length | --- ## 4. Signal vs. noise Rough split: **~70% actionable change-info, ~30% mechanism narrative**. This is the tightest entry of the series -- the "why" (silently discarding edits) is correctly brief. One phrase worth flagging: > *"was silently discarding Cold-Read compression edits that only touched CHANGELOG.md"* "Cold-Read compression edits" is insider framing. An adopter who doesn't know the Cold-Read discipline reads this as [GUESS: some kind of editorial process?]. The mechanism description "edits to CHANGELOG.md were silently ignored when the sidecar existed" is self-contained and clearer. The Cold-Read provenance belongs in the PR, not the changelog. --- ## 5. Structure & scannability - **Version header + date**: present (`## [v0.23.0] - 2026-07-02`). Good. - **Theme-summary line**: absent. v0.21.0 and v0.22.0 both carry a one-liner between the version header and the first section ("Post-v0.21.0 stabilization: ...", "Changelog tooling + release automation: ..."). v0.23.0 goes straight to `### Changed`. The theme is easy to state: "Sidecar retirement: CHANGELOG.md is now the single source of truth for release-body content." - **Section classification**: the sidecar retirement is in `### Changed`. It is more precisely a *removal* -- the sidecar file is no longer generated, `summary:` frontmatter is inert. `### Removed` would be the standard bucket. The BREAKING label is correct and prominent; the bucket is wrong. - **`### Removed / Deprecated` section**: absent. v0.22.0 established the precedent (`None.` when empty). This entry has non-trivial removals (sidecar file, effective inert-ing of frontmatter); the section should be present and populated, not omitted. - **`### Upgrade` section**: absent. v0.22.0 established the precedent. This is the sharpest gap: there IS a consumer action (`git rm .release-toolkit-release-notes.md` for legacy sidecar holders), but a reader scanning for the Upgrade section to answer "what must I do?" finds nothing. The action is in the prose, not where the reader looks. --- ## 6. Missing - **Theme-summary line** between version header and first section - **`### Removed / Deprecated` section** -- the sidecar feature and `summary:` frontmatter effectiveness are both removed; they belong here, not under Changed - **`### Upgrade` section** -- the `git rm .release-toolkit-release-notes.md` consumer action needs to be explicit and scannable, not embedded in prose - **No `### Added` or `### Fixed` sections** -- acceptable if genuinely empty, but worth confirming with `None.` per the standard (the body-linter checks for this) --- ## 7. Verdict Content quality is good -- the entry is accurate, the BREAKING label is prominent and warranted, and the prose is appropriately tight. The issues are structural, not prose-density: 1. **Add `### Upgrade` section** with the `git rm` action explicit. This is the highest-leverage fix: a BREAKING entry with a consumer action must answer "what do I do?" without requiring a paragraph read. 2. **Move sidecar retirement to `### Removed`** (or add a `### Removed` section that calls it out explicitly) -- `summary:` frontmatter becoming inert is a removal, not a change. 3. **Add theme-summary line** between the version header and the first section -- consistent with v0.21.0/v0.22.0 precedent. 4. **Cut "Cold-Read compression edits"** -- replace with "edits to CHANGELOG.md were silently ignored when the sidecar existed." Minor: confirm `### Added` / `### Fixed` are genuinely empty with `None.` entries (the body-linter will flag their absence). **Length verdict:** About right. One entry for a one-change release is correct. The restructuring above (Upgrade section + Removed section + theme line) adds ~4 lines and significantly improves the answer to the single most important reader question for a BREAKING entry.
docs(changelog): fold Pilot Cold-Read on #303 + manual sidecar removal (Route 1)
Some checks failed
changelog-body-check / changelog body Cold-Read linter (pull_request) Successful in 4s
Details
changelog-body-check / check (pull_request) Successful in 0s
Details
check-self-bootstrap / check (pull_request) Failing after 3s
Details
fragment-check / changelog fragment-kind (pull_request) Successful in 4s
Details
fragment-check / check (pull_request) Successful in 0s
Details
manifest-check / manifest-vs-tag consistency (pull_request) Successful in 5s
Details
manifest-check / check (pull_request) Successful in 0s
Details
check-self-bootstrap / check (push) Failing after 4s
Details
release / decide + act (push) Successful in 6s
Details
release / release (push) Successful in 0s
Details
11c990bbd2 
Pilot fired Cold Read on PR #303 (per the #628 discipline). Four
findings addressed:

1. **Missing ### Upgrade section** — added explicit `git rm` block
   for consumers with a legacy sidecar. Consumer action was buried in
   prose; scanners look for a dedicated Upgrade section.

2. **Sidecar retirement belongs in Removed, not Changed** — moved.
   Feature retirement is structurally a removal, not a behavioural
   change. Cleaner axis-decomposition per Pilot.

3. **Missing theme-summary** between version header and sections —
   added a one-line frame matching v0.21.0/v0.22.0 SOP precedent.

4. **Insider-framing** — "Cold-Read compression edits" replaced with
   "edits to CHANGELOG.md were silently ignored." Clearer to an
   outside reader who doesn't know the internal Cold-Read discipline.

Also: **manual bootstrap-fold per Route 1** (Bosun `f9b0`) —
`git rm .release-toolkit-release-notes.md`. The v0.23.0 cut runs
@v0.22.0 code which still writes + prefers the sidecar; removing it
here forces draft-release.sh's CHANGELOG fallback path and produces
the recursive proof-of-retirement (the fix's rollout is subject to
the invariant it fixes; the manual fold satisfies it once, v0.24.0
self-heals).

Same shape as #294 fragment-check bootstrap-fold precedent.

Result: 1227 chars (from 723 unadjusted, then structural additions
took it to a healthy under-ceiling shape). changelog-body-check
PASS.
Sign in to join this conversation.
Reviewers
No reviewers
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
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!303
No description provided.