Version control systems don’t do a good job of helping you out with things like this. They see “I’m looking for this text before and this text afterwards” and so if you have two paragraphs each inserting a paragraph of text in the same place, you won’t be able to merge the two of them—they will conflict.

I wish that you could specify merge behaviour on a file-by-file basis for something like Git, even as simple as “don’t worry about the text before when adding lines, just anchor it to the text after” which would equate to “append to section” in the earlier outlined case.

I'm aware of hundreds if not thousands of projects on GitHub alone using similar ways of documenting changes with CHANGELOG-like files and regardless of their size/popularity I'm not aware of the issues you both seem to be worried about.

Generally people edit changelogs after pull requests have been merged or as part of the pull requests themselves. It's far easier to figure out merge conflicts if and when other versions appended to the changelog simultaneously because all changelog entries are dated (or at least they should be) or at least versioned and contain plain text.

That said I agree that we should probably spend some time detailing common processes for editing and appending to a changelog in situations with concurrent branches being developed.

This is a real issue. I ask contributers to add a bullet at the top of NEWS.md and I frequently have to manually fix merge conflicts.

This is only a problem if you're handling multiple PRs simultaneously so your project has to reach a certain level of use before you'll see it.

Git does support custom merge "drivers" on a per file basis. For example: https://gist.github.com/seanh/378623

I wonder if it would be sufficient to set the changelog's merge strategy to union in .gitattributes.

I've tried this - it helps, but it's not a silver bullet. (And GitHub doesn't use it in PRs)