You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
CHANGELOG.md merge conflicts on every PR: introduce changelog fragments (changelog.d/) #295
Every PR adds its own bullet at the top of CHANGELOG.md under [Unreleased] / Fixed (or Added). All of them edit the same few lines, so as soon as one PR merges, every other open PR conflicts on CHANGELOG.md and the conflict has to be resolved by hand (see the repeated Merge remote-tracking branch 'origin/main' into fix/... commits in the history, e.g. #261, #271 and the trajectory PR #260). With ~10 PRs open at once this is constant busywork and a source of mistakes.
Proposal: changelog fragments
Each PR adds one new file instead of editing CHANGELOG.md. New files never conflict with each other, and the entries are folded into CHANGELOG.md once, at release time.
changelog.d/ with a README.md describing the convention. One file per PR, named changelog.d/<issue-or-pr-number>-<slug>.md. The first line is the category (Added, Changed, Deprecated, Removed, Fixed, Security); the remaining lines are the entry text, in the same style as the existing bullets.
tools/changelog_fragments.py (stdlib only, run as python -m tools.changelog_fragments):
check: validates every fragment (known category, non-empty text, unexpected files flagged).
release: folds all fragments into CHANGELOG.md under [Unreleased], grouped by category in Keep a Changelog order and appended below any existing bullets, then deletes the fragment files. It does nothing when there are none, so it is idempotent. Output is deterministic (sorted by file name). Optionally --version X.Y.Z --date YYYY-MM-DD renames [Unreleased] to ## [X.Y.Z] — YYYY-MM-DD, adds a fresh empty [Unreleased] and updates the compare links at the bottom, matching how 0.5.1 was cut.
Tests (offline, tmp_path) covering check and release, deterministic folding, and that changelog.d/README.md is ignored. Because they run in the normal suite, fragment validity is checked by pytest -q in CI.
CONTRIBUTING.md: the Pull requests checklist says to add a fragment instead of editing CHANGELOG.md.
Out of scope
No new GitHub workflow and no change to .github/; the pytest check is enough for now.
Existing CHANGELOG.md history is not rewritten; entries already under [Unreleased] stay where they are.
Open PRs that already edit CHANGELOG.md keep working; they can switch to a fragment when they next need a rebase.
The release routine (whoever cuts a release) runs release --version ... --date ... before bumping __version__; that is a follow-up outside this repo's code.
Activity
feat(changelog): changelog fragments so PRs stop conflicting on CHANG…