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

[Nathaniel Smith]

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.

-n

-- 
Nathaniel J. Smith -- https://vorpus.org