On Wed, Jun 12, 2019 at 12:58 PM Marten van Kerkwijk <m.h.vankerkw...@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 _______________________________________________ NumPy-Discussion mailing list NumPy-Discussion@python.org https://mail.python.org/mailman/listinfo/numpy-discussion
