Compose the list of changes in the code and on the wiki. If the issues have been updated with the appropriate milestone, the Github issue tracker should be able to provide a good starting point for this.
The above is a bit confusing to me, so asking for clarity to improve this perhaps with a PR from someone else who can quickly clarify it with the more knowledge. Then I'm happy to review that PR.
When we say: "list of changes in the code" -> do we really mean "to the code"?
When we say: "and on the wiki" -> what are we meaning or intending?
I think the above current quote is missing probably quite a few mini-steps within it? Imagine training a brand new Outreachy intern to do a release, for example.
I imagine that what we were intending was a simple stab at "prepare to generate Release Notes to be used when creating the Release." But as it is, it's a bit lightweight on "how should a maintainer generate and create some good Release Notes for OpenRefine", I.E. some mini-steps, I think.
Additonally, maybe we can script or automate generation of Release Notes for this prep step that can then be hand-edited to go into a Release description? Do Release notes have to be in the Release description nowadays with GitHub? Maybe this? Automatically generated release notes - GitHub Docs
This is a fairly burdensome part of the release process, that I have been looking into revamping for a while. This part of the release instructions were there when I arrived in the project, so I don’t know the full intentions behind them.
For a while, when I was essentially the only one merging pull requests, I tried keeping the discipline of updating the change log for the upcoming release as a wiki page. It’s was a bit tedious but it avoided having to review huge commit logs during the release process (spreading that work in my daily routines).
Now that we are more people merging PRs (which is amazing!), that’s not happening anymore and I try to fill the gaps when publishing releases.
But for a while I have been looking into setting up automation for this, based on the commit log. There are a few solutions for that:
GitHub’s own automatic generation, which is natively supported by the platform and uses similar configuration options
When I last checked Release Drafter, it relied on labels added to pull requests (not their linked issues) to determine how to categorize a change. Because we did not have a tradition of labeling PRs, I made a small script to transfer labels from issues to pull requests, which has been running okay for some time now (now it could be updated not to use scraping and only rely on the official API, since linked issues are now exposed there: #5574).
So, for 3.8 I would be keen to try those tools out (now that all the PRs merged since 3.7 should be correctly labeled). One useful thing is that those tools generally add the GitHub usernames of PR contributors in the logs, which GitHub then recognizes as “contributors to the release” - that will avoid GitHub declaring that I am the sole contributor to all releases, which has definitely been quite embarrassing so far! For 4.0-alpha2 I don’t think those automatically generated change logs will work given that they would expose a lot of internal changes which are not worth mentioning at such a granularity level to users.
One thing which could make this even smoother would be to have stricter guidelines about commit message formats, that we would need to establish and enforce. The generated changelog would then be more uniform (I assume that in the current state, some copy-editing will be required).
Make sure the PR title follows conventional commits messages (aslafy-z/conventional-pr-title-action@v3 works and reject the PR if the title is not valid)
Then add semantic-release as a github action when merging to main
Then you’re all set, automatic release notes and versions
Drawbacks
Not sure if there’s a way to hack into a release note to add some content
Not sure on how to add videos and links
Literaly one release per PR, lots of release notes
For a while, when I was essentially the only one merging pull requests, I tried keeping the discipline of updating the change log for the upcoming release as a wiki page. It’s was a bit tedious but it avoided having to review huge commit logs during the release process (spreading that work in my daily routines).
I would be happy to add both my own work and the work I merge to such a page. I just didn't know that one existed. Automatic release notes are in my experience a very blunt tool.
Compose the list of changes in the code and on the wiki. If the issues have been updated with the appropriate milestone, the Github issue tracker should be able to provide a good starting point for this.
The above is a bit confusing to me, [...]
I imagine that what we were intending was a simple stab at “prepare to generate Release Notes to be used when creating the Release.”
Yes, that's basically it. Remember that this is a checklist to be used by the project leader / product manager / release engineer, with this particular instruction focused at the product manager / project leader. It's never going to be done by an intern.
The nuance is that part of the preparation process includes: a) ordering the list so that the most important (to the user) stuff appears first and b) explaining and putting things in context so that the users know why they should care. Multiple PRs might get combined into a single note, if that's how users will think of it. That's the bit that gets done with your product manager hat on. Also, things which represent breaking changes for users or extension developers should receive special note.
Only a single list is needed, but it might get reformatted or subsetted for different contexts (announcement email, release notes, etc). The wiki reference above is to this portion of the wiki: https://github.com/OpenRefine/OpenRefine/wiki/Changes-for-3.7 A link to the full commit list as preserved on the branch serves as backup for those who need that level of detail.