Evaluate process for creating new release notes

Contributor & Development Discussion scikit-image
1

The current status quo for this process has us running tools/generate_release_notes.py to create an initial list of merged PRs since the last release. However, this still requires us to go through each item manually to arrive at a structured and descriptive documentation of each change. For the v0.20 release which was especially big this took a lot of work (see scikit-image#6556 and scikit-image#6766). For the current release we have currently settled on very light post-editing (see scikit-image#6925.).

In scikit-image#6925 (comment) I’ve “hinted” that the current approach is a bit to terse in my opinion.

With regard to the process, I think there are two things for us to decide:

  • A. What level of verbosity and detail are we aiming at for?
  • B. What process and tools do we use to facilitate this?

cc @jarrodmillman @stefanv

2

I think minimal requirements are to list all changes of the public API explicitly. Though, we probably don’t need the level of detail we used in v0.20. E.g. if we change a parameter in several functions, we should mention the parameter but don’t have to list every function. I think the bug fixes section is also required, especially if fixes impact the behavior of the API in subtle ways that might otherwise go unnoticed.

We can probably get rid of most of the documentation section. Maybe we still want to highlight new tutorials in a “New features and improvements” section.

So a shorter template structure might look like this:

  • Highlights
  • New features and improvements
  • Changes and new deprecations
  • Bug fixes
  • Other (for this section I think a list of PR titles would be enough)

@stefanv mentioned the idea to create release notes directly from pull request descriptions. The advantage I see here is that maintainers can easily update this themselves. A drawback is, that such a tool currently doesn’t exist.

There is towncrier, e.g. which is used by NumPy. I think we could get pretty close with that. I do like that it uncouples the 1-1 releationship between PR and description of a change. I like less that it’s not easy to add such a file from GitHub’s Web UI itself (perhaps with codespaces?).

1 Like
3

fwiw we have been tweaking this script over at napari and it’s getting close to what we want:

We have a non-mandatory “highlight” label in addition to the mandatory sections. Those PRs go into a narrative highlights section.

Our current script is here: docs/generate_release_notes.py at main · napari/docs · GitHub

1 Like
4

This is the direction I would prefer. I’ve been updating our generate_release_notes.py, which looks like it has a common ancestor to the napari script. I think adding the GHA actions and updating our generate_release_notes.py should suffice. It might be worth making this a SPEC.

5

+1 to using section “Highlights” this way: These would be just a few items (a short list) picked from the following (mandatory) section.

I would remove “new” and perhaps I would move this section to the top (following right after “Highlights”). API changes might not sound as exciting as new features but, in a way, they are more important to be aware of.

My $0.02

6

+1 to using section “Highlights” this way

Fully agree. The way the script at https://github.com/scikit-image/scikit-image/pull/6961 is currenty setup, PRs can show up in multiple sections as long as they have the appropriate tag and I plan to keep it that way.