ci: let release-please own CHANGELOG.md (end the dual-changelog desync) - #110
Merged
Conversation
CHANGELOG.md had drifted 13 releases out of date: the hand-curated file was frozen at 0.8.0 with ~240 lines piled in a stale `[Unreleased]` block, while release-please's real per-release history was routed to a hidden `.release-please-changelog.md` "sink" nobody read. Root cause: a manual "rename [Unreleased] -> [X.Y.Z] before merging" step that was skipped for every release after 0.8.0. Point release-please's `changelog-path` at CHANGELOG.md so it owns and regenerates the changelog from Conventional Commits — no manual step, can never desync again. Seed CHANGELOG.md with the full generated history (0.5.0 -> 0.21.1) and delete the sink. Update CONTRIBUTING.md, the release-please workflow comment, and the commitizen comment to match. Versioning itself was already correct and is unchanged: bump-minor-pre-major (release-please) and major_version_zero (commitizen) agree, so pre-1.0 breaking changes bump MINOR — intended SemVer 0.x behavior.
mountainowl
force-pushed
the
chore/release-changelog
branch
from
June 17, 2026 01:39
987afe7 to
e183eaf
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
While auditing the release mechanics I found the versioning is solid (see below) but the changelog had silently desynced 13 releases ago:
CHANGELOG.md(hand-curated, shipped in the sdist) was frozen at 0.8.0, with ~240 lines piled into a stale## [Unreleased]block..release-please-changelog.md"sink" that isn't shipped or linked.[Unreleased]→[X.Y.Z]before merging" step — skipped for every release after 0.8.0.What
changelog-pathatCHANGELOG.md→ it now owns and regenerates the changelog from Conventional Commits. No manual step, can never desync again.CHANGELOG.mdwith the full generated history (0.5.0 → 0.21.1); delete the sink file.CONTRIBUTING.md, the release-please workflow comment, and the commitizen comment to describe the new (automated) reality.Versioning audit (no change needed)
The major number not increasing is by design, not a bug:
release-pleasesetsbump-minor-pre-major: trueandcommitizensetsmajor_version_zero: true— they agree that pre-1.0, breaking changes bump MINOR. Verified breaking changes are detected (7 releases carry⚠ BREAKING CHANGES) and bumped minor correctly; tag = manifest = pyproject =0.21.1;commitlint.ymlonly lints (cz check), so there's no dual-writer conflict.