[python-committers] what's going on with Misc/NEWS?

[Brett Cannon]

On Fri, May 24, 2013 at 9:00 AM, Nick Coghlan <ncoghlan at gmail.com> wrote:
> On Fri, May 24, 2013 at 10:24 PM, Brett Cannon <brett at 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?