Skip to content

Changes in CHANGELOG.md lead to merge conflicts/issues

Old problem

Git does not merge changes in changelogs in a good way, often leading to either merge conflicts or a badly merged changelog. Consider the following example:

on the main-branch we have CHANGELOG.md with the following contents:

# Changelog
## Unreleased
changes to A (!xxx)

and there's a merge request open for a branch whose CHANGELOG.md contains

# Changelog
## Unreleased
changes to B (!yyy)

Natively, git cannot merge these two, leading to an error message

Auto-merging CHANGELOG.md
CONFLICT (content): Merge conflict in CHANGELOG.md
Automatic merge failed; fix conflicts and then commit the result.

This will occur every time something gets merged into the main branch, and can be quite annoying.

Old Solution

Back in October we introduced !495 (merged) which involved changing the merge strategy for CHANGELOG.md, by adding the line CHANGELOG.md merge=union to .gitattributes.

This produces a nice changelog after a successful merge

# Changelog
## Unreleased
changes to A (!xxx)
changes to B (!yyy)

New problem

When we create a release one of the maintainers modifies the changelog on the main-branch:

# Changelog
## Unreleased

## Release vx.y.z (yyyy-mm-dd)
changes to A (!xxx)
changes to B (!yyy)

But this causes issues with all open merge requests. If one merge request has the following CHANGELOG.md

# Changelog
## Unreleased

changes to A (!xxx)
changes to B (!yyy)
changes to C (!zzz)

This will get merged as

# Changelog
## Unreleased

## Release vx.y.z (yyyy-mm-dd)
changes to A (!xxx)
changes to B (!yyy)
changes to C (!zzz)

and the change is moved to the release, whereas it is supposed to stay under ## Unreleased. Every open merge request thus requires a manual change to the CHANGELOG.md. Another issues also appear that I was unable to reproduce in this example, where entries are duplicated.

New solutions

As discussed during the developer's meeting of 23/02/2023, we can consider a few solutions.

  1. Do nothing
  2. Revert back to the old style of merging CHANGELOG.md (i.e. removing CHANGELOG.md merge=union from .gitattributes).
  3. Create two changelogs, e.g. CHANGELOG_dev.md and CHANGELOG_released.md. Any unreleased change will go inside CHANGELOG_dev.md and after a new release we clear CHANGELOG_dev.md and update CHANGELOG_dev.md. See !609 (closed) for implementation details and further discussion.