On reducing “Changelog” merge conflicts

There are number of attempts to reduce amount of changelog conflicts. All of them are not working for me. Except new one.

tl;dr Directory structure to the rescue: https://github.com/nettsundere/cyberlog

  • Some people use placeholders. Good idea.
“At GitLab we solved the above problem by adding a 100 lines with just a hyphen placeholder at the top of the changelog.” https://about.gitlab.com/2015/02/10/gitlab-reduced-merge-conflicts-by-90-percent-with-changelog-placeholders/
  • Some people use different merge strategy for single file(merge=union). It is good idea to go when every line of your changelog are always unique. It is bad idea when your changelog has some not-so-unique endings. Things then can just go wrong. And nobody will notice it. All similar stirngs can be silently merged into one during conflict resolution.

Sometimes i’m just spending hours of my time just by fixing CHANGELOG merge conflicts. Yep. Lets fix it using 2-dimensional file storage called folders.


We associate one feature with its changelog entry (file) belonging to some version (folder).

Now we can manage this changelog changes easilly. We can revert our feature-commit. Nothing bad happens. We can add some features to the same branch without any conflicts at all. Changelog entry can be as complex as you want it.

Now you can stop adding whitespaces killed by your editor preferences just to avoid messing around with your colleagues changes. Now people can be happy instead of rebasing every time you accept one more pull-request.


This is how feature change looks now in diff. You see only meaningful changes.

Required software

Actually there is no required software to follow this strategy. But it will be good to see entire changelog or version at once. So i decided to create project called “Cyberlog”

Cyberlog help screen

For now you can find here limited set of features. You can operate on entries and versions. You can see changes from some version, entry or all changes.

Things to do

  • Customization using template engine (hipster integration)
  • SCM integration (git-blame and others)
  • Convertation option (useful to convert your old CHANGELOG to a new one, supported by Cyberlog)
  • Different presenters (maybe you need a pdf?)

Things not to do

  • Edit entry feature. You should use your preferred text? editor to edit logs. Even photoshop looks good enough. I can imagine changelog filled with meaningful pictures, videos and audios explaining changes.

Project source code (BSD3) is available via https://github.com/nettsundere/cyberlog