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.
- Do nothing
- Revert back to the old style of merging
CHANGELOG.md
(i.e. removingCHANGELOG.md merge=union
from.gitattributes
). - Create two changelogs, e.g.
CHANGELOG_dev.md
andCHANGELOG_released.md
. Any unreleased change will go insideCHANGELOG_dev.md
and after a new release we clearCHANGELOG_dev.md
and updateCHANGELOG_dev.md
. See !609 (closed) for implementation details and further discussion.