Skip to content

CHANGELOG: fold the stale Unreleased block into v1.0.0 rather than deleting it #136

Description

@forkwright

Finding

CHANGELOG.md's Unreleased section advertises as unshipped a body of work that shipped a month
ago, and the record of that work exists nowhere else in the file.

Evidence

The Unreleased entries cite #37, #38, #40#43, #45#47 — Phase 5 CPU reranker, Phase
6a GDN CPU reference, Phase 6b TurboQuant, and the associated contracts and fixtures.

The released sections cover #78, #84, #85, #87, #100, #110, #111. No Unreleased
reference appears in any released section.

v1.0.0 (2026-07-29) is the oldest release in the repo:

$ gh api repos/forkwright/logismos/releases --jq '.[-1] | .tag_name + " " + .published_at'
v1.0.0 2026-07-29T15:36:30Z

Why this matters

The cause is structural, not an oversight. release-please generates changelog sections from
conventional commits going forward from the release it manages, so anything predating its first
cut never receives a version heading. That work did ship — inside v1.0.0 — but the changelog has no
heading saying so.

Two failure modes follow, and they pull in opposite directions:

  • Leaving it: the file claims real, shipped capability is still unreleased. Anyone reading it to
    decide what a version contains is misled.
  • Deleting it (attempted in docs(changelog): clear the Unreleased section release-please never touches #134, closed): removes the only human-readable record of what v1.0.0
    contained. That trades a wrong statement for a missing one, and a missing record is harder to
    notice later than a wrong one.

Desired correction

Move the Unreleased entries under the ## [1.0.0] heading where the work actually landed, and
leave Unreleased empty for release-please to own going forward.

Two things to settle while folding rather than carrying across verbatim:

  • gh pr view resolves none of #37#47 in this repo. Those references may point at issues, or
    at another repo entirely. Correct them during the fold.
  • Whether backfilling a v1.0.0 body is the right convention here at all is a judgement about this
    repo's changelog, worth deciding explicitly rather than silently inside a cleanup.

Done when: Unreleased is empty, no shipped capability is described as unreleased, and every
entry currently in that block is still findable in the file under the version that shipped it.

Provenance

Split out of #134, which correctly identified the defect and proposed deletion. Closed in favour of
this.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions