An alternative I've seen work well is to put changelog= comments in the patch descriptions and automatically gather them at release time.
An alternative I've seen work well is to put changelog= comments in the patch descriptions and automatically gather them at release time.
I'd agree this is an area we need to clarify for version 0.4.0 and forward.
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.
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 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.
Writing a changelog progressively is the only way you’re likely to end up with it being good. Consider the whole point of the “unreleased” section, too. If you put it off, you’ll just keep on putting it off, and when you finally do make a release you’re unlikely to put enough effort into the changelog.
Your changelog will be better if you write it at the time of development, not release. To be sure, you’ll want to check over it at release time or even before then, but there’s no rule against amending the changelog at any time.