On Fri, May 24, 2013 at 9:00 AM, Nick Coghlan <ncoghlan@gmail.com> wrote:
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.
I don't know about you, but my first sentence (i.e. up to \n\n) is essentially what I put into NEWS anyway so making it work so that developer details go after that is not really an issue. Yes, coming up with a way to flag commits as not NEWS-worthy would be needed, but I don't think that would be difficult.
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).
I sent a followup email to myself but unfortunately Gmail sent it from another address so it got rejected.
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 :)
I think that's overly complicated. I don't see why we need anything more than simply NEWS/3.4, NEWS/3.3, etc. and just split the files per feature release since that's the interest (and merge) boundary. And do we really need a merged NEWS file at that granularity?