making use of auto-generate release note generate for next release

[shimwell]

Is your feature request related to an enhancement? Please describe.

On the theme of reducing the amount of work required for releases I wonder if it might be a good time to make use of the new auto-generate release notes feature on github releases. This has a few time saving features

• Automatically adds titles of all PRs to a list of features along with links to the PR
• Automatically adds all authors of the release as authors on the release
• Adds a nice link to a diff showing the changes from previous release to the new release.

If we are not happy with the standard layout generated by the auto-generate release notes then we can add a yaml formatting file
https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes#example-configuration

In our case this would also allow us to remove the need for adding details to the change log.
There would also be one less thing for new contributors to learn before making a PR.

Is your feature request related to a problem? Please describe.

Saves time writting the release notes, reduces commits (no change log commit needed), reduces failed CI (due to missing change log entry)

Describe the solution or outcome you'd like.

A clear and concise description of what you want to happen.
For this to work we have to ensure that PR titles are meaningful as this is what appears in the release notes. PR titles can be edited by repo maintainers so this shouldn;t be a problem.

Describe alternatives you've considered.

A clear and concise description of any alternative solutions or features you've considered.
We could stick with the changelog system

Here is an example of auto-generated release notes

[pshriwise]

I'm very on board w/ this @shimwell! Good motivation for using labels in our PRs and issues more consistently. I also like that it will reduce noise in our commits.

Question and thought:

• Is there a way to label PRs so they don't appear in release notes? We probably don't want trivial PRs w/ typo fixes to appear in the release summary, for example.
• We'll want to update our developer's guide and PR template to note that the PR title and labels now matter.

One fundamental change in adopting this approach is that the changelog is no longer part of the repository itself, meaning we're relinquishing our summary of changes to GitHub. I'm okay with that since we always have the git history itself and the changelog is tied to GitHub itself.

[gonuke]

My only concern is at the intersection of @pshriwise's question about omitting small/trivial PRs. In our current paradigm, the PR number can be associated with another related entry in the CHANGELOG. If feature is added in PR X and a small tweak/improvement/bug fix to that code is in PR Y, we can list both (X, Y) in the line for that feature.

We could do this manually at release? But that is trading off distributed manual labor at the time of PR for concentrated manual labor at the time of release.

[gonuke]

Look at PR 170 & 172 in the screenshot above, for example...

[shimwell]

In the situation where we have a tiny PR which we don't want to include then we can just delete that line of text from the auto-generated text.

Currently the releaser has to write all the review text, with this approach the releaser would just have to read the auto-generated text and delete minor PRs. They can also correct the names of PR.

[shimwell]

Thanks for spotting those small PRs I have edited the release text to remove them 😄

No more PR 170 or 172 in the release details

[gonuke]

@pshriwise - there seems to be some nice control over which PRs get included with labels, and the ability to have sections in this with certain labels mapped to certain sections. E.g. Additions vs Bug Fixes vs Build System, etc...

[shimwell]

Now with a section called testing improvements

[pshriwise]

@pshriwise - there seems to be some nice control over which PRs get included with labels, and the ability to have sections in this with certain labels mapped to certain sections. E.g. Additions vs Bug Fixes vs Build System, etc...

Nice! I was hoping so. Just wanted to check.

[pshriwise]

Yeah, it looks like this feature would do the trick!

changelog.categories[*].exclude.labels | A list of labels that exclude a pull request from appearing in this category.

[gonuke]

Currently the releaser has to write all the review text, with this approach the releaser would just have to read the auto-generated text and delete minor PRs. They can also correct the names of PR.

Not really true. RIght now the author of the PR has to contribute to the release text. There is almost no work to do on the part of the releaser!

[gonuke]

This could potentially create more work for the releaser where it makes sense for multiple PRs to be included in the same change entry. That is, it's not uncommon for us to have multiple PRs that all relate to a single conceptual change, that may be best referred to in a single change entry. This occurs when tweaking CI configurations and/or iterating to asymptotically improve some new feature. Right now the PR author can choose to introduce a delta in the Changelog by just adding the PR number to an existing line in the Changelog. Using the automated tools, those will necessarily be 2 different entries. Moreover, those entries may be removed from each other in the autogenerated list, possibly being a little confusing for readers. At the very least, I'd like to see them grouped near each other, and ever better would be merging them into a single entry. The releaser will have to do this work, and so I anticipate that it won't happen. I recognize that this may be a rather controlling view, and many of you may not care as much about this. If there is a strong community sense that this is not important, I'll follow along with that.

[gonuke]

If we do make this change, we'll want to make some intentional decisions about how we review PRs to include:

• review of the PR title to be appropriate for inclusion in the change log
• review of the PR tags to allow us to use specific tags to group the change log in semantically meaningful ways as we do now

[shimwell]

Perhaps we can add a check box to PULL_REQUEST_TEMPLATE, somthing like this

• PR has meaningful title