New release note strategy after branching 1.17.

classic Classic list List threaded Threaded
12 messages Options
Reply | Threaded
Open this post in threaded view
|

New release note strategy after branching 1.17.

Sebastian Berg
Hi all,

we had discussed trying a new strategy to gather release notes on the
last community call, but not followed up on it on the list yet.

For the next release, we decided to try a strategy of using a wiki page
to gather release notes. The main purpose for this is to avoid merge
conflicts in the release notes file. It may also make things slightly
easier for new contributors even without merge conflicts.
Any comments/opinions about other alternatives are welcome.

We probably still need to fix some details, but I this will probably
mean:

1. We tag issues with "Needs Release Notes"
2. We ask contributors/maintainers to edit the initial PR post/comment
with a release note snippet. (I expect maintainers may typically put in
a placeholder as a start for the contributor.)
3. After merging, the release notes are copied into the wiki by the
user or a contributor. After the copy happened, the label could/should
be removed?

SciPy uses a similar strategy, so they may already have some experience
to do it slightly different that I am missing.

Best Regards,

Sebastian

_______________________________________________
NumPy-Discussion mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/numpy-discussion

signature.asc (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: New release note strategy after branching 1.17.

ralfgommers


On Wed, Jun 12, 2019 at 4:59 PM Sebastian Berg <[hidden email]> wrote:
Hi all,

we had discussed trying a new strategy to gather release notes on the
last community call, but not followed up on it on the list yet.

For the next release, we decided to try a strategy of using a wiki page
to gather release notes. The main purpose for this is to avoid merge
conflicts in the release notes file. It may also make things slightly
easier for new contributors even without merge conflicts.
Any comments/opinions about other alternatives are welcome.

We probably still need to fix some details, but I this will probably
mean:

1. We tag issues with "Needs Release Notes"
2. We ask contributors/maintainers to edit the initial PR post/comment
with a release note snippet. (I expect maintainers may typically put in
a placeholder as a start for the contributor.)
3. After merging, the release notes are copied into the wiki by the
user or a contributor. After the copy happened, the label could/should
be removed?

SciPy uses a similar strategy, so they may already have some experience
to do it slightly different that I am missing.

Sounds great to me. It's actually a little more formalized already then what we do for SciPy. I like the "needs release notes" label ideae.

Cheers,
Ralf


_______________________________________________
NumPy-Discussion mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/numpy-discussion
Reply | Threaded
Open this post in threaded view
|

Re: New release note strategy after branching 1.17.

Charles R Harris
In reply to this post by Sebastian Berg


On Wed, Jun 12, 2019 at 8:59 AM Sebastian Berg <[hidden email]> wrote:
Hi all,

we had discussed trying a new strategy to gather release notes on the
last community call, but not followed up on it on the list yet.

For the next release, we decided to try a strategy of using a wiki page
to gather release notes. The main purpose for this is to avoid merge
conflicts in the release notes file. It may also make things slightly
easier for new contributors even without merge conflicts.
Any comments/opinions about other alternatives are welcome.

We probably still need to fix some details, but I this will probably
mean:

1. We tag issues with "Needs Release Notes"
2. We ask contributors/maintainers to edit the initial PR post/comment
with a release note snippet. (I expect maintainers may typically put in
a placeholder as a start for the contributor.)
3. After merging, the release notes are copied into the wiki by the
user or a contributor. After the copy happened, the label could/should
be removed?

SciPy uses a similar strategy, so they may already have some experience
to do it slightly different that I am missing.


As an aid to future automation once the note is in the PR summary, we might want to add a selection of  `notes: section` labels. The notes are also in RST which is not completely compatible with MD, so we might want to be careful about some things. Maybe put everything in a codeblock?

Chuck


_______________________________________________
NumPy-Discussion mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/numpy-discussion
Reply | Threaded
Open this post in threaded view
|

Re: New release note strategy after branching 1.17.

Brigitta Sipocz
In reply to this post by Sebastian Berg
> 3. After merging, the release notes are copied into the wiki by the
> user or a contributor. After the copy happened, the label could/should
> be removed?


In astropy we keep our "whats-new-needed" label around, so people
doing the release can double check that everything is indeed ended up
in the document, and it's still a good balance of topics (some things
seemed to be what's new worthy at the beginning, but a few weeks/month
later at the time of the actual release they might not be exciting any
more).

Brigitta
_______________________________________________
NumPy-Discussion mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/numpy-discussion
Reply | Threaded
Open this post in threaded view
|

Re: New release note strategy after branching 1.17.

Nathaniel Smith
In reply to this post by Sebastian Berg
It might be worth considering a tool like 'towncrier'. It's automation to support the workflow where PRs that make changes also include their release notes, so when the release comes you've already done all the work and just have to hit the button.

On Wed, Jun 12, 2019, 07:59 Sebastian Berg <[hidden email]> wrote:
Hi all,

we had discussed trying a new strategy to gather release notes on the
last community call, but not followed up on it on the list yet.

For the next release, we decided to try a strategy of using a wiki page
to gather release notes. The main purpose for this is to avoid merge
conflicts in the release notes file. It may also make things slightly
easier for new contributors even without merge conflicts.
Any comments/opinions about other alternatives are welcome.

We probably still need to fix some details, but I this will probably
mean:

1. We tag issues with "Needs Release Notes"
2. We ask contributors/maintainers to edit the initial PR post/comment
with a release note snippet. (I expect maintainers may typically put in
a placeholder as a start for the contributor.)
3. After merging, the release notes are copied into the wiki by the
user or a contributor. After the copy happened, the label could/should
be removed?

SciPy uses a similar strategy, so they may already have some experience
to do it slightly different that I am missing.

Best Regards,

Sebastian
_______________________________________________
NumPy-Discussion mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/numpy-discussion

_______________________________________________
NumPy-Discussion mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/numpy-discussion
Reply | Threaded
Open this post in threaded view
|

Re: New release note strategy after branching 1.17.

Eric Wieser
It's worth linking to the issue where this discussion started, so we avoid repeating ourselves - 

Eric

On Wed, Jun 12, 2019, 11:51 Nathaniel Smith <[hidden email]> wrote:
It might be worth considering a tool like 'towncrier'. It's automation to support the workflow where PRs that make changes also include their release notes, so when the release comes you've already done all the work and just have to hit the button.

On Wed, Jun 12, 2019, 07:59 Sebastian Berg <[hidden email]> wrote:
Hi all,

we had discussed trying a new strategy to gather release notes on the
last community call, but not followed up on it on the list yet.

For the next release, we decided to try a strategy of using a wiki page
to gather release notes. The main purpose for this is to avoid merge
conflicts in the release notes file. It may also make things slightly
easier for new contributors even without merge conflicts.
Any comments/opinions about other alternatives are welcome.

We probably still need to fix some details, but I this will probably
mean:

1. We tag issues with "Needs Release Notes"
2. We ask contributors/maintainers to edit the initial PR post/comment
with a release note snippet. (I expect maintainers may typically put in
a placeholder as a start for the contributor.)
3. After merging, the release notes are copied into the wiki by the
user or a contributor. After the copy happened, the label could/should
be removed?

SciPy uses a similar strategy, so they may already have some experience
to do it slightly different that I am missing.

Best Regards,

Sebastian
_______________________________________________
NumPy-Discussion mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/numpy-discussion
_______________________________________________
NumPy-Discussion mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/numpy-discussion

_______________________________________________
NumPy-Discussion mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/numpy-discussion
Reply | Threaded
Open this post in threaded view
|

Re: New release note strategy after branching 1.17.

Sebastian Berg
In reply to this post by Nathaniel Smith
On Wed, 2019-06-12 at 11:45 -0700, Nathaniel Smith wrote:
> It might be worth considering a tool like 'towncrier'. It's
> automation to support the workflow where PRs that make changes also
> include their release notes, so when the release comes you've already
> done all the work and just have to hit the button.
>

We discussed that a bit. I think one issue is that none of us had much
experience with it. There was a notion that towncrier might be a
steeper learning curve for new/one-time contributors compared to a
wiki/summary editing approach (which probably could be automated or
semi automated at some point).

But to be honest, if you suggest that we should give it a better look
or even a try, I do not think anyone had strong feelings about it. I
cannot say I looked at those two options (towncrier, and I think what
cpython uses) close enough to have an opinion.

- Sebastian


> On Wed, Jun 12, 2019, 07:59 Sebastian Berg <
> [hidden email]> wrote:
> > Hi all,
> >
> > we had discussed trying a new strategy to gather release notes on
> > the
> > last community call, but not followed up on it on the list yet.
> >
> > For the next release, we decided to try a strategy of using a wiki
> > page
> > to gather release notes. The main purpose for this is to avoid
> > merge
> > conflicts in the release notes file. It may also make things
> > slightly
> > easier for new contributors even without merge conflicts.
> > Any comments/opinions about other alternatives are welcome.
> >
> > We probably still need to fix some details, but I this will
> > probably
> > mean:
> >
> > 1. We tag issues with "Needs Release Notes"
> > 2. We ask contributors/maintainers to edit the initial PR
> > post/comment
> > with a release note snippet. (I expect maintainers may typically
> > put in
> > a placeholder as a start for the contributor.)
> > 3. After merging, the release notes are copied into the wiki by the
> > user or a contributor. After the copy happened, the label
> > could/should
> > be removed?
> >
> > SciPy uses a similar strategy, so they may already have some
> > experience
> > to do it slightly different that I am missing.
> >
> > Best Regards,
> >
> > Sebastian
> > _______________________________________________
> > NumPy-Discussion mailing list
> > [hidden email]
> > https://mail.python.org/mailman/listinfo/numpy-discussion
>
> _______________________________________________
> NumPy-Discussion mailing list
> [hidden email]
> https://mail.python.org/mailman/listinfo/numpy-discussion

_______________________________________________
NumPy-Discussion mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/numpy-discussion

signature.asc (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: New release note strategy after branching 1.17.

Marten van Kerkwijk
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.).
-- Marten


_______________________________________________
NumPy-Discussion mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/numpy-discussion
Reply | Threaded
Open this post in threaded view
|

Re: New release note strategy after branching 1.17.

Stefan van der Walt
On Wed, 12 Jun 2019 15:57:48 -0400, Marten van Kerkwijk 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.).

IPython does something very much like this: they put .rst files inside
whatsnew/pr/x.rst and then have a script to merge all these into the
release notes:

https://ipython.readthedocs.io/en/stable/coredev/index.html?highlight=whatsnew#create-github-stats-and-finish-release-note

It looks like Jupyter Notebook is not using that system, so not sure how
much mileage they got out of it.

Best regards,
Stéfan
_______________________________________________
NumPy-Discussion mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/numpy-discussion
Reply | Threaded
Open this post in threaded view
|

Re: New release note strategy after branching 1.17.

Nathaniel Smith
In reply to this post by Marten van Kerkwijk
On Wed, Jun 12, 2019 at 12:58 PM Marten van Kerkwijk
<[hidden email]> 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
[hidden email]
https://mail.python.org/mailman/listinfo/numpy-discussion
Reply | Threaded
Open this post in threaded view
|

Re: New release note strategy after branching 1.17.

Marten van Kerkwijk
The attrs like you sent definitely sounded like it would translate to numpy nearly trivially. I'm very much in favour!
-- Marten

_______________________________________________
NumPy-Discussion mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/numpy-discussion
Reply | Threaded
Open this post in threaded view
|

Re: New release note strategy after branching 1.17.

Sebastian Berg
In reply to this post by Nathaniel Smith
On Wed, 2019-06-12 at 17:34 -0700, Nathaniel Smith wrote:

> On Wed, Jun 12, 2019 at 12:58 PM Marten van Kerkwijk
> <[hidden email]> 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
>

_______________________________________________
NumPy-Discussion mailing list
[hidden email]
https://mail.python.org/mailman/listinfo/numpy-discussion

signature.asc (849 bytes) Download Attachment