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

[Nick Coghlan]

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.

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 at gmail.com   |   Brisbane, Australia