Skip to content

Stop the root changelog claiming the release maintains it - #115

Merged
vjovanov merged 2 commits into
mainfrom
fix/root-changelog-points-at-the-real-one
Aug 30, 2026
Merged

Stop the root changelog claiming the release maintains it#115
vjovanov merged 2 commits into
mainfrom
fix/root-changelog-points-at-the-real-one

Conversation

@vjovanov

Copy link
Copy Markdown
Owner

CHANGELOG.md opened by saying the Unreleased section of docs/changelog.md is what "release automation promotes into a numbered section here at release time", citing §FS-rhei-distribution.5.

That section says the promotion happens inside docs/changelog.md, archiving the displaced release under docs/changelog/. It says nothing about this file, and prepare_changelog_release.py never opens it — its --changelog default is docs/changelog.md.

So the file documented a behaviour that has never run, and drifted exactly as far as that implies:

  • no 0.2.0, 0.3.0 or 0.3.1 section — it stops at 0.1.0
  • an Unreleased note still announcing project-qualified ticket ids as a forthcoming breaking change, eight days after they shipped in 0.2.0

That note is what nearly sent me to a minor bump while cutting 0.3.1; the pending entries were patch-appropriate all along. And CHANGELOG.md ships inside the published crate, so it is the first changelog a reader meets.

The change

The header now says where the changelog actually is and that this file is not maintained by the release. The stale Unreleased note is deleted.

The 0.1.0 section stays, which is the one judgment call here. My first draft replaced the whole file with a pointer; checking before deleting showed docs/changelog/0.1.0.md is a four-line summary, so CHANGELOG.md is the only place the initial release's feature list and its crates.io naming limitation are recorded. Making the file uniform would have quietly lost them.

Verification

grund check output byte-identical to main. No new links introduced — docs/changelog/ is written as inline code, not a directory link, since the repo has no precedent for one and lychee gates links in CI.

Noted, not fixed here: release-plan.md:226 still says to create the GitHub release "from the CHANGELOG.md entry", which the release workflow has not done for some time — it extracts the inline section from docs/changelog.md. That file is explicitly the 0.1.0-era plan, so it wants its own pass.

🤖 Generated with Claude Code

https://claude.ai/code/session_01ANPWuKoibZ6NS84tJxeDC8

`CHANGELOG.md` opened by saying the `Unreleased` section of
`docs/changelog.md` is what "release automation promotes into a numbered
section here at release time", citing §FS-rhei-distribution.5. That section
says the promotion happens inside `docs/changelog.md`, with the displaced
release archived under `docs/changelog/`. Nothing has ever written to this
file, and `prepare_changelog_release.py` does not open it.

So the file documented a behaviour that never ran, and drifted exactly as far
as that implies: no `0.2.0`, `0.3.0` or `0.3.1` section, and an `Unreleased`
note still announcing project-qualified ticket ids as a forthcoming breaking
change eight days after they shipped in 0.2.0. It ships inside the published
crate, so it is the first changelog a reader meets.

The header now says where the changelog is and that this file is not
maintained by the release. The stale `Unreleased` note is gone.

The `0.1.0` section stays. `docs/changelog/0.1.0.md` is a four-line summary,
so this is the only place the initial release's feature list and its crates.io
naming limitation are written down; deleting it to make the file uniform would
lose them.
@vjovanov
vjovanov merged commit 12a431c into main Aug 30, 2026
4 checks passed
@vjovanov
vjovanov deleted the fix/root-changelog-points-at-the-real-one branch August 30, 2026 09:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant