Process for updating release notes after a release

[pdurbin]

Our newish process for creating release notes is working well: https://guides.dataverse.org/en/5.5/developers/making-releases.html#write-release-notes

However, updating release notes after a release can be problematic. There is drift between the live release notes and the version in git.

Here are the failure scenarios:

• A pull request updates the version in git but the change doesn't make it to the live notes.
• The live notes are edited and the change is not propogated back to git. (This is less of a problem for end users and impossible for 4.15 and below where release notes aren't even in git.)

Possible solutions:

• Delete the version from git as part of the release process. No syncing to worry about. Only one source of truth. This is how the release notes are pre 4.16 anyway.
• As part of the merge process, copy the content from the updated file in git to the live release note.
• Write scripts to check if the files in git and the live release notes are in sync.
• Automate pushing content from the files in git to the live release notes.

Questions:

• With millions of projects on GitHub, we aren't the only one with this problem, are we? What do other projects do?
• Having the files in git makes it easier for contributors to edit the release notes. Should we keep this?

[djbrooke]

• First solution is the easiest (disadvantage would be losing history)
• We should investigate the other solutions as well
• @djbrooke to request a feature from Github to point release notes at a file
• Notes cut off in the releases area - this bit us in v5 where we had long release notes

[djbrooke]

Possibly useful Github action:

https://github.com/marketplace/actions/upload-files-to-a-github-release

[donsizemore]

GitHub Releases may or may not help here https://github.blog/2021-10-04-beta-github-releases-improving-release-experience/

[pdurbin]

I had a thought that even if we delete the files from git it would probably be best to check (before deleting) if any changes need to be propagated to the live notes.

It's easy enough to eyeball the list and see that 5.0, 5.3, and 5.4 have been updated in recent months:

Another option would be to write a script that compares the files in git to what we pull down programatically from the GitHub API. From https://docs.github.com/en/rest/reference/repos#get-a-release-by-tag-name here's how we can get the live version from 4.16:

curl -H "Accept: application/vnd.github.v3+json" https://api.github.com/repos/IQSS/dataverse/releases/tags/v4.16

[djbrooke]

Thanks @pdurbin and @donsizemore for talking about this, and thanks extra to Don for tracking down the differences. I'd like to get us into a state where just the live release notes (on the Github releases page) live on after a release instead of trying to keep the two copies in sync. We lose version control on the notes and it makes updating the notes less self-service, but it avoids the syncing problem. I think they steps generally here are:

• update the live notes to make sure they reflect the most recent changes
• update the release notes guidance in the dev guide
• add a step to release cutting that involves deleting the release notes file
• perhaps add an issue template for documentation updates (and use the opportunity to add a blurb on release notes changes post-release)
• provide feedback to GitHub about the releases process

[poikilotherm]

Sorry to bother, but would it really be that hard to create an update from a git file?

There are actions like https://github.com/softprops/action-gh-release and as I read the description, they can edit existing releases.

A GH action would be necessary not acting on a new tag but on updates to certain paths (allows regexes) on develop only...

It's pretty cool to have reviewable PRs for release note changes... 😉

[djbrooke]

@poikilotherm thanks for sharing the link. I shared https://github.com/marketplace/actions/upload-files-to-a-github-release upthread but it wasn't quite a match for what I wanted to do. What you shared looks to be more aligned.

I'm not opposed to this, but I don't have much experience with adding new GitHub actions. Would you like to discuss and possibly work together on this?

[poikilotherm]

Maybe we can create a little side repository to test a few options for this?

[pdurbin]

@poikilotherm what about testing on https://github.com/gdcc/sword2-server ?

[poikilotherm]

@poikilotherm what about testing on https://github.com/gdcc/sword2-server ?

No way... Creating tags means automated release to Maven Central