Resolving Changelog Merge Conflict Madness

Sean Wallis

7 november 2018

Resolve madness

We start with an innocent looking changelog.

[gist id=”863b3bcef6e19c505f4a4ec2aa3c805b”]

Harmless right? OK, so the above is a simplified version of the real thing, but we get the structure. It’s based upon the Keep a Changelog format; so for each release we have Added, Changed and Removed headings where applicable. It’s also more than just a changelog. It gets built into a webpage using Fractal, which in turn resolves the component path links we see above on build.

So what’s the problem?

For every story in the release, we must add something to the changelog. In fact we need a separate entry for every change, removal or addition to any component. Which can lead to multiple changelog entries per story. Then imagine we have many stories in progress at the same time. As soon as one story gets merged into our development branch, all other stories have merge conflicts to resolve. Then we must resolve conflicts continually as we work to get anything through. Madness!

How do we solve this

Fortunately this isn’t a new problem. GitLab experienced a very similar changelog conflict crisis, which gave us the basis for our solution. Quite simply, we stop making all of our changes in one file, and instead place our changes within unique files in a changelogs/unreleased folder. For the unreleased change files we use a simple yaml file corresponding to the story you are working on.

So let’s say story-5 is to add something to the carousel, whilst removing something from the footer component.

[gist id=”c6fb0ffb191a1d6a6aa7b9a14adae418″]

In the above file we only need to add the type, component and description for each change. The rest is taken care of by a script on our pipeline that runs when we create our release.

Problem solved.

This article was also published on