3 ms·
This is fine for smaller, low-velocity projects, but tends to result in merge conflicts in high-velocity projects. An alternative I've seen work well is to put
by skybrian 10y ago
This is fine for smaller, low-velocity projects, but tends to result in merge conflicts in high-velocity projects.
An alternative I've seen work well is to put changelog= comments in the patch descriptions and automatically gather them at release time.
- derefr 10y agoI don't see how; presumably a CHANGELOG should only be updated as part of release engineering, not during development. It's a document owned by whoever bumps the version number.
- bluejekyll 10y agoI find it easier to maintain one while you make the changes, thus I would see the issue being referred to.
- chrismorgan 10y agoSpeaking in the context of an open-source project: 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.
- olivierlacan 10y agoA common convention we showcase in the Keep a Changelog changelog itself (https://github.com/olivierlacan/keep-a-changelog/blob/604e382bf3a438613691405efb072769fde22e08/CHANGELOG.md#unreleased https://github.com/olivierlacan/keep-a-changelog/blob/604e38...) is to have an [Unreleased] section at the top of the changelog. It rarely conflicts with other branches of a project because it only becomes a version prior to or after a merge into the main branch (trunk/master/etc.). I'd agree this is an area we need to clarify for version 0.4.0 and forward.
- chrismorgan 10y agoVersion 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.
- olivierlacan 10y agoI'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.
- hadley 10y agoThis 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.
- tom9729 10y agoGit does support custom merge "drivers" on a per file basis. For example: https://gist.github.com/seanh/378623 https://gist.github.com/seanh/378623