feat(prep): a release without fragments gets its notes from feat/fix commit subjects #1529
Labels
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
No milestone
No project
No assignees
1 participant
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
frankenbit/release-toolkit#1529
Loading…
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
An adopter whose commit subjects are Conventional Commits cannot get release notes from them. Since #717 (ADR-0011),
rt prepbuilds the version section only fromchangelog.d/fragments and### Kindblocks under## [Unreleased], and a commit subject only sets the bump. No setting changes that, and an unknown key inrelease-toolkit.ymlis refused.frankenbit/storey wants exactly this from its next release on:
type(area): the finding (#issue)(storey109d985).Measured at
8086700:internal/prep/prep.go:216-217:renderCommitsis a stub that returnsnil, nil. The overview comment at:22readsccMd = nil // #717: CC is bump-only.internal/config/config.go:150:KnownFields(true). With a v0.63.0 build on a Storey clone, arelease_notes:key makesrt prepandmanifest-checkfail, whilert decidefalls back to defaults and exits 0.internal/prep/prep.go:186-199: recovery subtractsFragmentSectionsfrom a stranded section. Its comment says that ifrenderCommitsever returns notes,FragmentSectionsmust render them too, or recovery folds them back and the re-prepare renders them again (#1490, review 7155).cmd/rt/recover_pending_cut.go:400: recovery refuses a prepare that deleted no visiblechangelog.d/*.md. A cut whose notes came only from commits could therefore never be recovered.docs/conventions.md:34-35:feat:andfix:are documented as "bump only".A prototype already exists: +846/−72, written on
dd871e8, and it applies cleanly to8086700. It adds the key, restores the pre-#717 renderer from2f78688^behind it, and makes recovery subtract the stranded prepare's commit notes.main.compose-verifypasses on the rendered section.golang:1.25.Why it matters
Decisions taken (for review; recorded as a decision tree in ADR-0012)
release_notes: {source: fragments|commits}; leaving it out meansfragments.commitsstill renders fragments and[Unreleased]prose, and a numeric fragment<N>.<kind>.mdreplaces every commit bullet that cites#N.featgoes to Added andfixto Fixed.perfandrefactorstay bump-only, because rendering them would also needrt decide's release-relevance predicate to change, or a note could be lost in the cut race.Release-Notes: skipin the commit's own body. For a subject that already landed, putRelease-Notes: skip <sha>in a later commit's body. Neither needs a history rewrite.Acceptance criteria
With no
release_noteskey,rt prepoutput is byte-identical for every adopter and for toolkit-self. The four ADR-0011 tests stay green, and a mutation-verified guard proves the default path makes no commit walk.— DONE @ #1531 (
e5fcf1d, reviewed ase5fcf1d), restated for the per-release rule. There is no key. A release with a fragment or authored[Unreleased]text renders byte-identically tomain. That was measured on Storey's pending v0.2.0, and on toolkit-self's first run of the new code: rolling PR #1523 (v0.65.0) renders exactly its five fragments. The four ADR-0011 tests stay green, adapted to the rule.TestCompose_noCommitWalkUnlessTheCutHasNoOtherSourceandTestComposeFragmentsAndBumpOnlyCommitsfail when such a release calls git, and mutants that walk anyway or ignore the fragments were killed.With
release_notes.source: commits,rt preprenders thefeat/fixsubjects since the last tag as- **scope**: descriptionbullets under Added/Fixed. They are scrubbed byregister.ScrubLine, and there is no blank-line split between fragment bullets and commit bullets.— DONE @ #1531 (
e5fcf1d, reviewed ase5fcf1d), without the key: every release with no other note source renders this way,featunder Added andfixunder Fixed, each bullet throughregister.ScrubLine. Breaking changes of any type also render, under Upgrade. The blank-line criterion no longer applies: with mixed mode dropped, fragment bullets and commit bullets never share a release.These render no bullet:
changelog.d/*.md;Release-Notes: skip, or named by a laterRelease-Notes: skip <sha>.A numeric fragment suppresses the bullets that cite its number.
— DONE in part @ #1531 (
e5fcf1d, reviewed ase5fcf1d); the rest was superseded. BothRelease-Notes: skipforms are implemented (TestCompose_commitNotesOwnSkipTrailer,TestCompose_commitNotesSkipNamedSHA). The three fragment-driven rules went with mixed mode: any fragment now makes the whole release a fragment release, so no commit bullet renders beside one. An empty fragment declines the notes of a whole release.When opted in,
rt recover-pending-cutneither duplicates commit notes nor refuses a prepare whose notes came only from commits. When the config cannot be loaded and may carry the key, it refuses instead of falling back.— DONE @ #1531 (
e5fcf1d, reviewed ase5fcf1d). Recovery detects which source the stranded release used. It takes commit notes out instead of folding them back, and it accepts a prepare that consumed no fragment (TestRecoverPendingCutModeDetection,TestRecoverPendingCutCommitModePrepare). It refuses whenrelease-toolkit.ymldoes not load (TestRealRecoverDepsCommitNotesNeedALoadedConfig). With no key, there is nothing more to guard.Rendering refuses when the commit range cannot be anchored (no last tag, but the CHANGELOG has a prior cut). The last-tag match follows
tag_formatinstead of a hard-codedv*.— DONE @ #1531 (
e5fcf1d, reviewed ase5fcf1d), and extended. The window starts at the tag of the CHANGELOG's newest cut, matched throughtag_format, and rendering refuses when that tag cannot be found. The operator accepted two more cases with ADR-0012:Documentation:
— DONE @ #1531 (
e5fcf1d, reviewed ase5fcf1d), restated. ADR-0012 is accepted (2026-10-03) and supersedes ADR-0011 in part, for a release with no fragment and no[Unreleased]text. Its details are indocs/adr/0012-commit-subject-release-notes-details.md. C6, conventions.md, integration.md, fragment-style.md, the README and the arc42 statements are updated. The C1 schema is unchanged againstmain. The pin-before-key warning no longer applies: integration.md says adopters need only the pin bump.The native Windows and
golang:1.25suites pass, and the PR shows a dry run on a Storey-shaped repository.— DONE @ #1531 (
e5fcf1d, reviewed ase5fcf1d). All 30 packages pass natively on Windows and on Linux. The earlier rounds ran ingolang:1.25. The last code round (b20b59e) ran in CI's own image (forgejo-ci-go:latest), where golangci-lint reports 0 issues. The PR description reports the Storey dry runs. On the landed commit, all 46 checks are green.A
changelog.dfragment.— DONE @ #1531 (
e5fcf1d, reviewed ase5fcf1d):changelog.d/1529-commit-notes.changed.md, already consumed into v0.65.0's### Changedby rolling PR #1523.Out of scope
perf/refactor, a breaking-change marker onfeat!, and PR-time subject grading.perf/refactorand subject grading stay out of scope.Anchor
The release-notes plan for frankenbit/storey, 2026-10-01 to 2026-10-03. Adoption tracker: #1478.
git add --all -- changelog.d(AGENTS.md section 5a) instead of relying on the verb to create the directory #1537rt prep --dry-runinside a linked worktree stages the whole preview into that worktree's index — the scratch copy shares its .git #1538feat(prep): render Conventional Commit subjects as release notes for adopters who opt in (release_notes.source: commits)to feat(prep): a release without fragments gets its notes from feat/fix commit subjectsClosing by hand: every acceptance criterion is ticked in the description.
e5fcf1dd8c5afc80ea1f7601a64f34044750da1donmain, via #1531. It is a fast-forward rebase, and all 18 commits are identical to the reviewed head (git range-diff: 18 of 18=). The landing-identity record (comment 114675) says the same.e5fcf1d.e5fcf1dare green, the push run included.claude/1529-commit-noteswas deleted on merge.The redesign changed several criteria during review: there is no key, mixed mode was dropped, and breaking changes render under Upgrade. The description has an outcome note at the top, and each criterion says what was done.
One correction to #1531's description: it says the companion document lists the mutants, and it does not. The mutation runs were done in the implementing session and are not recorded in the repository.