On Fri, May 24, 2013 at 9:00 AM, Nick Coghlan <ncogh...@gmail.com> wrote: > On Fri, May 24, 2013 at 10:24 PM, Brett Cannon <br...@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? _______________________________________________ python-committers mailing list python-committers@python.org http://mail.python.org/mailman/listinfo/python-committers
