Automate building release notes

[daxpryce]

I just wrote them for 0.3.0 by hand, and I feel like with a bit of discipline we can automate the entire thing. There has to be something out there.

So, for anyone who wants to help out, I'd love to make this task be a not-human-task.

[jcob-sikorski]

I can work on this! How structure of release notes should look like? And from what source should I aggregate each new feature/significant change?

[daxpryce]

Hi @jcob-sikorski!

We started requesting a meaningful PR title, such that it could be roped into release notes. What we'd need (or want?) is a way of rolling all of those up into a list that we could push into the release rst file.

Superficially it sounds easy enough, but I'm not sure how to automate it such that it happens within our CICD workflow. We don't want it happening with every PR, we do want it happening prior to a full release, we could conceivably add it to the list as we go (e.g. if a PR is merged and closed, have a github action automatically turn that PR title into a line in the RST file and open a new PR for it, but we wouldn't want that PR, when merged and closed, to trigger a new cycle).

Rather than be prescriptive about what to do, I'll just tell you what we would like:

• PR titles from previous release until now aggregated in chronological order and added to the release RST file. It should be manually reviewed and merged so that we can adjust the wording or add further detail (or combine things, if appropriate) - but what we really want is a decent starting point for a human to use to actually finalize the last release notes prior to doing a non-pre-release.
• It shouldn't require local tooling, if at all possible, because that can be error prone. I prefer the approach of "let a computer get things in order and have a human for the final gate and any minor modifications" over "have it fully automated" or "have it fully in meatspace".

I hope you take this on, but I understand if it isn't that exciting a task to take on. Let me know what you think!

[jcob-sikorski]

I'm excited to work on that task!

But first, you have to tell what you mean by "turn that PR title into a line in the RST file and open a new PR for it, but we wouldn't want that PR, when merged and closed, to trigger a new cycle"

[daxpryce]

Sure, let me explain some background details first:

The way our release process via CICD works is:

• Any PR merged into dev cuts a new pre-release (see: https://pypi.org/project/graspologic/#history )
• When we're happy with things and ready to do a full release, we merge dev -> main. This signals the CICD pipeline that it shouldn't craft a 1.0.1dev1805910598150981509815098159081509851 style version number, but instead commit to using 1.0.1
• Prior to this merge to main, we want to create a list of PRs, titles only, that have been merged into dev from PREVIOUS_RELEASE (e.g. 1.0.0) until NOW(), format them as per ReStructuredText (rst) format in our release file, and open a new PR (called the release's Release Notes PR. It's a fancy name.)
• The format doesn't have to be identical, just basically hitting the conceptual boxes of "has a meaningful title that a user of graspologic would be able to make sense of" and "has a link to the PR number/url in it" somehow.
• The release's Release Notes PR doesn't need to go into the list of PR titles though (because then the release notes would include 'updating release notes', and that's just silly)
• Since it's a PR, the maintainer merging it can look at it, tweak some things if they need to, then merge it into dev right before they merge dev into main and BAM! Release notes will be published.

I don't think it's unreasonable to have a maintainer manually launch a "create release notes" github action via a manual trigger - I just want to make sure the tooling for it is all 100% on a github action runner vs. running in a local environment, that way nobody has to do any local setup. If a maintainer forgets to do the release notes documentation update prior to release, that's on them. There's a bit of manual work in this process in general, if only because a human does have to do the merge from dev to main AND also update the setup.cfg version number in dev to get ready for the next pre-releases - as much of that manual stuff we can direct a computer to do, even if it requires a human to monitor it, the better.

Let me know if you need some more clarification!

[jcob-sikorski]

Why dates of pre-releases on graspologic site are different from dates of closed and approved PRs?

[daxpryce]

Why dates of pre-releases on graspologic site are different from dates of closed and approved PRs?

I have no idea and now I'm digging into it. All I can imagine is something failed in the artifact upload but the actions didn't treat it as a failure, which ... would be bad. So! I have to dig into this deep today. This is really odd though.

[daxpryce]

@jcob-sikorski That list of PRs is a list of all PRs, some of which are to dev and main, some of which aren't.

They actually match up pretty well with https://github.com/microsoft/graspologic/actions/workflows/publish.yml and then also with the releases in PyPI!

I wonder if there's a way in the github rest api to ask for all the PRs that have been closed and merged to dev only? Or maybe that's something that has to be filtered afterwards?

[jcob-sikorski]

Script is ready to deploy but I wonder how this action should be triggered. I saw this post which describes ON MERGE event but it's not that clear to me.

[jcob-sikorski]

Are there any events specific to merging dev -> main? I'm looking for the events that could trigger workflow action run. Another option would be to run script manually right before dev->main merge.

[jcob-sikorski]

Tool ready for pull request! It will run only when setup.cfg file changes.