Prevent automatic changelog merging

Question

I have the following setup:

• I use Keep a Changelog (https://keepachangelog.com/)
• I use Git with GitHub
• I follow the Gitflow Workflow

Precondition: The changelog is saved in a file named CHANGELOG.md in the develop branch which looks partly like the following:

## [Unreleased]
- Feature2

## [1.0.0]
- Feature1

Than I create a feature branch of it. In the feature branch a new feature 3 was added to the changelog:

## [Unreleased]
- Feature2
- Feature3

## [1.0.0]
- Feature1

Afterwards a release was made from the develop branch and merged back to it, which looks like this then:

## [Unreleased]

## [1.1.0]
- Feature2

## [1.0.0]
- Feature1

If I now merge the develop branch into the feature branch the CHANGELOG.md file is merged automatically (without conflicts) and looks like:

## [Unreleased]

## [1.1.0]
- Feature2
- Feature3

## [1.0.0]
- Feature1

Problem: The auto-merge put the Feature3 on the wrong place (beneath 1.1.0 instead of Unreleased). To prevent this I found only one solution: marking this file as binary in .gitattributes (to always raise conflicts). But .gitattributes is not evaluated by GitHub.

Question: Keep a changelog, Git and GitHub seem like state of the art. Why does nobody else have the same problem? At least I couldn't find any question or solution about it.

What is confusing me even more: A lot of people ask for the opposite of my problem. They get a conflict and want to auto-merge it with merge=union. Do I misunderstand something or is my approach wrong?

Answer 1

This is what's called a semantic conflict. The code merges correctly without conflicts, but the result is not what you wanted. Unfortunately, as Git is not omniscient, it cannot know what you intended, and so these things happen sometimes.

Even if GitHub did support merge=binary, you wouldn't want that behavior, because it would practically mean that merging your changelog would cause a conflict every time the file changed both on the main branch and in a feature branch. This would be very inconvenient in a busy project.

In general, changelogs are tricky in situations like this not just because they are prone to semantic conflicts, but more often, they just experience actual conflicts due to multiple PRs including lines in the same place. As a result, you may wish to either generate your changelog from some other source or use an approach similar to how GitLab does it and use a single file per entry, accumulating them all into the changelog just before release.