Merge-Conflicts in CHANGELOG.md
Merge Conflicts
Whenever someone adds a new feature, fixes a bug, deprecates a function or removes something from the code, a changelog entry should be created. This actually means, nearly each MR adds a line into the CHANGELOG.md
. If there are two MRs at the same time (what is always the case) and one gets merged, the second cannot be merged without rebasing to the latest commit. This is frustrating and increases the development-time.
Can we solve this problem somehow?
There was a similar discussion going on in the group of gitlab developers, see a summary of this discussion process here: https://about.gitlab.com/blog/2018/07/03/solving-gitlabs-changelog-conflict-crisis/
The solution they propose is an automatic changelog tool. But the steps before are: instead of directly filling up a CHANGELOG.md
, add entries into separate .yml files in a directory, e.g., CHANGELOG/unreleased/
. These entries are then merged into one markdown file in the release process. There are some subtleties in this process, but those could be solved.
Another idea would be: Add the changelog entry only after the MR is reviewed, directly before there merge. Then there might be less merge conflicts but we need to remember to do this. It has another consequence: The additional commit of an entry in the CHANGELOG file requires another CI pipeline run. This is a wast of computing resources, but also increases the time for a merge. A workaround of this problem could be to add an exception to the .gitlab-ci.yml
file that when some listed files are changed only, no pipeline will be created.
Changelog format
Another aspect I have learned from reading about changelog files is to use a proper changelog format for better following the changes, see, e.g., https://keepachangelog.com/en/1.1.0/ or https://docs.gitlab.com/ee/development/changelog.html. The summary is: sort changelog entries in some categories, e.g.,
- added: New feature
- fixed: Bug fix
- changed: Feature change
- deprecated: New deprecation
- removed: Feature removal
- performance: Performance improvement
- other: Other
What do you think about this? Should we improve the handling of changelogs or is this "work without benefits"?