[Numpy-discussion] New release note strategy after branching 1.17.

[Sebastian Berg]

On Wed, 2019-06-12 at 17:34 -0700, Nathaniel Smith wrote:
> On Wed, Jun 12, 2019 at 12:58 PM Marten van Kerkwijk
> <m.h.vankerkwijk at gmail.com> wrote:
> > Overall, in favour of splitting the large files, but I don't like
> > that the notes stop being under version control (e.g., a follow-up
> > PR slightly changes things, how does the note gets
> > edited/reverted?).
> > 
> > Has there been any discussion of having, e.g., a directory
> > `docs/1.17.0-notes/`, and everyone storing their notes as
> > individual files? (A bit like maildir vs a single inbox file.) At
> > release time, one would then simply merge/order the files. Beyond
> > staying within git, an advantage of this may be that automation is
> > easier (e.g., if the file is always called <issue-number>.rst, then
> > checks for it can be very easily automated.).
> 
> That's exactly how towncrier works, except the filenames also have a
> category like "bugfix" or "feature" so they can be sorted into the
> right section of the final release notes. Here's how some projects
> describe it in their contributing docs:
> 
> https://pip.pypa.io/en/stable/development/contributing/#news-entries
> https://www.attrs.org/en/latest/contributing.html#changelog
> https://trio.readthedocs.io/en/latest/contributing.html#release-notes
> 
> Oh, and it uses a single fixed directory, like 'docs/release-notes',
> without the version in the directory name, and as part of preparing
> the release you delete all the files in that directory after moving
> them into the final release notes. This way if a PR is originally
> targeted at 1.17 but slips to 1.18, you can't accidentally put the
> note in the wrong directory. It's also nice for backports, where the
> same bugfix might appear in 1.17.0 and 1.16.1 – the backport
> automatically carries the note along with it and it just works.
> 

Those are nice features. Do you have experience that this is not very
difficult for new users, numpy possibly gets more one-time contributers
than others? I think that was the only reason we had for not being sure
about it. I am not sure we gave the fact that it is not inside version
control much thought (e.g. you could automate scraping PRs as well, we
already do that to some degree).

Maybe it is a point anyway to try it. Scipy currently uses the other
method. And right now we have the manpower to have maintainers push a
release notes commit if that should proof a bit of an issue (and it is
likely not much harder than the current "please edit this file",
especially for users making a change that needs a release note).

- Sebastian


> -n
> 
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: This is a digitally signed message part
URL: <http://mail.python.org/pipermail/numpy-discussion/attachments/20190612/20c2d050/attachment.sig>