Retrospective finding — refs #10.
Context
Across the retrospective sample, changelog writing is in good shape — but four of eight repos
ended with their entire history sitting in ## [Unreleased] despite shipped artifacts, a
built-but-never-triggered tag pipeline, or versioned outputs already in use elsewhere. Where
releases were cut, the changelogs are exemplary. The failure is never the writing — it's that
the standard defines how to keep [Unreleased], but names no moment at which to cut it, so solo
projects simply never do.
Side effect observed: a years'-worth [Unreleased] block accretes append-position churn (entries
pasted out of order) and stops being readable as "what's new".
Proposal
Add a short "when to cut a release" section to the commit/changelog conventions:
- Cut triggers — cut a version the first time any of these happens: an artifact is handed to
anyone else (deployed, published, installed on a second machine), a version number is stamped
into any output, or a tag pipeline exists and has never fired.
- Checklist line in the pre-PR/pre-commit checklist: "does
[Unreleased] describe more than
one shippable unit? If yes, cut."
- Documented lightweight variant for genuinely never-versioned repos (internal ops repos):
dated changelog entries instead of versions — one repo in the sample already does this well;
make it an official, declared variant instead of an ad-hoc deviation.
- Optional CI nudge: warn when
[Unreleased] exceeds N entries while release machinery
exists in the repo.
Tasks
Acceptance criteria
- The standard answers "when do I cut?" in one place, with the no-version variant defined.
- A repo with a tag pipeline and a fat
[Unreleased] gets flagged by checklist or CI, not by
archaeology.
— 🤖 Claude, on behalf of @PBNZ
Retrospective finding — refs #10.
Context
Across the retrospective sample, changelog writing is in good shape — but four of eight repos
ended with their entire history sitting in
## [Unreleased]despite shipped artifacts, abuilt-but-never-triggered tag pipeline, or versioned outputs already in use elsewhere. Where
releases were cut, the changelogs are exemplary. The failure is never the writing — it's that
the standard defines how to keep
[Unreleased], but names no moment at which to cut it, so soloprojects simply never do.
Side effect observed: a years'-worth
[Unreleased]block accretes append-position churn (entriespasted out of order) and stops being readable as "what's new".
Proposal
Add a short "when to cut a release" section to the commit/changelog conventions:
anyone else (deployed, published, installed on a second machine), a version number is stamped
into any output, or a tag pipeline exists and has never fired.
[Unreleased]describe more thanone shippable unit? If yes, cut."
dated changelog entries instead of versions — one repo in the sample already does this well;
make it an official, declared variant instead of an ad-hoc deviation.
[Unreleased]exceeds N entries while release machineryexists in the repo.
Tasks
Acceptance criteria
[Unreleased]gets flagged by checklist or CI, not byarchaeology.
— 🤖 Claude, on behalf of @PBNZ