Skip to content

CHANGELOG.md merge conflicts on every PR: introduce changelog fragments (changelog.d/) #295

Closed

Description

@Birfy

Problem

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.

  1. 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.
  2. 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.
  3. 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.
  4. 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.

Single PR to follow.

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

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions