On Fri, May 24, 2013 at 10:24 PM, Brett Cannon <brett@python.org> wrote:
I was trying to do a simple merge of a doc change between 3.3 and default and the usual Misc/NEWS conflict came up. But when I looked at the diff it was massive! Turns out that Misc/NEWS in default goes from 3.3.1rc1 to 3.4.0a1 (http://hg.python.org/cpython/file/24ffb0148729/Misc/NEWS) while Misc/NEWS in 3.3 goes properly through all versions between 3.3.1rc1 to 3.3.3rc1 (http://hg.python.org/cpython/file/3c4a5dc29417/Misc/NEWS).
I have to get to work so I don't have time to fix this, but if someone does have the time to unwind this mix-up that has accumulated that would be great. And maybe it's finally time to bite the bullet and come up with some way to automatically generate Misc/NEWS from commit messages.
No, commit messages do not a NEWS file make. The audiences are different (current and future developers vs interested end users), so it doesn't make sense to try to use the same content. Using commit messages also makes it annoyingly difficult to edit erroneous entries, as well as needing to come up with conventions to indicate commits which *shouldn't* get a log entry.
What *does* make sense is to use a directory structure (which version control systems handle nicely) rather than a single file (which is prone to spurious context based conflicts). Twisted has their notion of "topfiles (see https://twistedmatrix.com/trac/wiki/ReviewProcess#Newsfiles) and for Beaker we adopted the model of simply dumping draft release note snippets into a "whatsnew/next" subdirectory and using a Sphinx wildcard to display them in the draft docs (we edit them into something more coherent as part of the release process, since they're our equivalent of What's New rather than NEWS).
For Python, it would make sense to me if we took the existing subcategories in NEWS and turned them into a NEWS.in directory tree:
NEWS.in/
legacy.txt # The NEWS contents from past releases
3.4.0a1/
core/
misc.txt # Any changes with no tracker entry
issue12345.txt # Single bullet point
issue54321.txt # Single bullet point
...
library/
...
tests/
...
docs/
...
c-api/
...
idle/
...
build/
...The trunk NEWS.in would then end up with full notes for all branches that have been merged forward. The NEWS file generation for each version would be designed to take care of matching up the corresponding maintenance releases when deciding which entries to include.
Of course, we've talked about doing something like this before, it's just never irritated anyone enough for them to sit down and *write* the associated NEWS file generator, or the code to split the existing NEWS file for the active branches :)
Cheers, Nick.
-- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia