Skip to content

"[Unreleased] is not a terminal state" — add release-cutting triggers to the standard #13

Description

@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, 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:

  1. 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.
  2. Checklist line in the pre-PR/pre-commit checklist: "does [Unreleased] describe more than
    one shippable unit? If yes, cut."
  3. 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.
  4. Optional CI nudge: warn when [Unreleased] exceeds N entries while release machinery
    exists in the repo.

Tasks

  • Extend the commit-conventions reference with the cut triggers + the dated-entries variant.
  • Add the checklist line.
  • Provide the CI nudge snippet (opt-in).

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions