On 6 August 2015 at 19:59, M.-A. Lemburg
I had mentioned a fourth one:
4. Add a NEWS field to the issue tracker and use it's content for the file entry
This is how eGenix does it and it's been working great so far. We simply have our issue tracker generate a report and use this as basis for the change log when cutting a release.
The advantage over checkin messages is that you are not stuck if you have multiple checkins for a single issue which should only have a single entry in the change log.
Without using the issue tracker, this is similar to approach #2 you mentioned above, but with only creating that file once during the release process instead of patching it up with every single checkin.
This is fairly similar to the way Red Hat does it for downstream products - the docs team figure out the Errata text for end users based on the bug, then that's mapped to the right places accordingly. Eventually pursuing that approach would give us a few rich tiers of information: * full commit logs * commit logs filtered to just be those which mention bug numbers * issue tracker NEWS items mentioned in commit entries * the What's New documentation However, given that we're always going to be able to generate full commit logs, and the filtered logs that mention issues, I think that makes for a good place to start, even if we end up adding a new field to the tracker later. After all, we'll always need to write commit messages regardless of what else we do. Something I *would* like to address up front is how we're going to deal with errors in commit messages (especially cases where we've failed to mention an issue number, or have mentioned the wrong one). However, having a commit log based generator offers a relatively decent way to deal with that: a Misc/NEWS.overrides directory, with filename prefixes based on the commit hashes to be overridden. Dealing with the forward merges will also be necessary - existing projects https://pypi.python.org/pypi/gitchangelog may provide useful ideas on that front. If we wanted to get particularly fancy, commits that added versionadded and versionchanged tags to the documentation could also be automatically highlighted. Regardless, I think one thing I'm figuring out from this discussion is that there *shouldn't be* a NEWS file in the repo itself - the repo will contain the source data, but the rendering can happen separately rather than being done incrementally on each commit. This means that the renderer can be developed in parallel with the current process, with some seed data used to capture the state of the NEWS file as of a particular commit. Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia