Blog Engineering How we solved GitLab's CHANGELOG conflict crisis
July 3, 2018
2 min read

How we solved GitLab's CHANGELOG conflict crisis

How we eliminated changelog-related merge conflicts and automated a crucial part of our release process.


Since its [very first commit] more than six years ago, GitLab has had a changelog
detailing the noteworthy changes in each release. Shortly after [Enterprise
Edition (EE) was introduced], it [got a changelog of its own]. Whenever anyone
– whether it was a community contributor or a GitLab employee – contributed a
new feature or fix to the project, a changelog entry would be added to let users
know what improved.

As GitLab gained in popularity and started receiving more contributions, we'd
constantly see merge conflicts in the changelog when multiple merge requests
attempted to add an entry to the list. This quickly became a major source of
delays in development, as contributors would have to rebase their branch in order
to resolve the conflicts.

This post outlines how we completely eliminated changelog-related merge
conflicts, removed bottlenecks for contributions, and automated a crucial part
of our release process.

At the beginning, GitLab's CHANGELOG file would look something like this:

v 8.0.0 (unreleased)
  - Prevent anchors from being hidden by header (Stan Hu)
  - Remove satellites
  - Better performance for web editor (switched from satellites to rugged)
  - Faster merge
  - ...
  - Ability to fetch merge requests from refs/merge-requests/:id

v 7.14.1
  - Improve abuse reports management from admin area
  - Ability to enable SSL verification for Webhooks

v 7.14.0
  - Fix bug where non-project members of the target project could set labels on new merge requests.
  - Upgrade gitlab_git to 7.2.14 to ignore CRLFs in .gitmodules (Stan Hu)
  - ...
  - Fix broken code import and display error messages if something went wrong with creating project (Stan Hu)

When a developer made a change in the upcoming release, 8.0.0 in this example,
they would add a changelog entry at the bottom:

index de2066f..0fc2c18 100644

We want to hear from you

Enjoyed reading this blog post or have questions or feedback? Share your thoughts by creating a new topic in the GitLab community forum. Share your feedback

Ready to get started?

See what your team could do with a unified DevSecOps Platform.

Get free trial

New to GitLab and not sure where to start?

Get started guide

Learn about what GitLab can do for your team

Talk to an expert