Then as part of the release process, somebody (usually me) uses `git log --grep` to find all the commit messages that developers thought to be change log relevant and writes a document that can be consumed by end users (including screenshots of the features etc).
This way end-users can still be informed about changes (most don't care, some notice and complain even when one pixel has moved to a different spot), but we never have issues with merges or rebases (at least not related to change log maintenance :p)
Also, in my opinion, keeping a change log for developers is completely unnecessary these days with git and other tools to provide very quick and easy access to the revision history.
But for end-users it still makes sense, though it of course has to be on a higher level than individual commits.
But regarding git conflicts, I've set up dpkg-mergechangelogs as a global merge driver and it works decently well for cherry-picking things within Debian packages represented as git repos. In ~/.gitconfig:
[core]
attributesfile = ~/.gitattributes
[merge "dpkg-mergechangelogs"]
name = debian/changelog merge driver
driver = dpkg-mergechangelogs -m %O %A %B %A
debian/changelog merge=dpkg-mergechangelogs
Something like: security issues, breaking changes, major features, major bugfixes, minor features, minor bugfixes.
lastTag = `git describe --abbrev=0 --tags`
git log --oneline --no-merges #{lastTag}..HEAD | cut -c 9- | sort
If you have something like a changelog, it's important to keep the audience in mind. In this case the audience was mainly the internal test department and marketing. Testers also had access to the bug tracker of course and only used the changelog to get an overview. Marketing and support used the changelog as the basis for their communication with customers.
It's actually pretty simple - you keep CHANGELOG updates to their own commit, and just aggressively rebase into that commit as you prepare the release. The release owner is the only person who works on the CHANGELOG. We do that at Snowplow and it works really well. Here is the WIP commit for the CHANGELOG for the next Snowplow release: https://github.com/snowplow/snowplow/commit/a862b1e4ab935184...
When we finish a release, the CHANGELOG becomes the GitHub release notes: https://github.com/snowplow/snowplow/releases/tag/r60-bee-hu...
We are approaching 1 issue : 1 commit : 1 CHANGELOG entry but it's not always possible, and a huge number of open source software users are not technical enough to parse a git log anyway.
Every file in every commit should be meaningful for the given commit. These are obviously usually source files or even documentation of the current behavior of the software. The problem with CHANGELOG and NEWS files that they are not meaningful to every single commit only for commits that are tagged as releases.
I don't know what would be a good practice to manage change logs in a repo. I'm sure that it shouldn't be in a project's git repo though. Maybe having a separate git repo for managing releases would help, like have your original project as a submodule and keep release specific files in this separate repo. Obviously it looks more complicated but it's better than managing merge conflicts between CHANGELOG files when there is no meaning of the CHANGELOG for the merge commit anyway.
Sumup:
> At GitLab we solved the above problem by adding a 100 lines with just a hyphen placeholder at the top of the changelog. People can insert their entry at a random location in the changelog. There is still a chance of conflict when two merge requests change the same line but it is greatly reduced. It looks a bit strange to have these empty lines on top so we added a comment to explain their purpose..
For an actual log of individual changes, that's what "git log" is for; any project that pre-dates git should "git mv ChangeLog ChangeLog.pre-git". And if your "git log" output isn't highly readable, write better commit messages and group changes into more logical commits; once you stop breaking "git rebase -i", that gets a lot easier.
Some of this advice potentially makes sense, but for a NEWS file, not a changelog. A NEWS file has one top-level heading per release, containing the release notes for that release, summarizing the key user-visible changes. However, that file should not attempt to track every change, should not contain times or dates, and should get grouped in logical chunks rather than chronological order.
And while it can potentially make sense to update that file as part of the commit introducing a new user-visible change, that also reintroduces the same conflict and collaboration issues as a changelog, so personally I only update NEWS files right before a release. I run a script that generates a properly formatted NEWS entry based on the version and git commit messages (turning each one into a markdown bullet-list entry with indentation), then edit the result to add headings, group entries under those headings, and delete any non-user-visible changes that don't merit a release note.