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.).
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:
New features and improvements
Changes and new deprecations
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?).
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.
+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.