search

IQSS / dataverse

Open source research data repository software
http://dataverse.org
Other
882 stars 493 forks source link

Process for updating release notes after a release #7988

Closed pdurbin closed 2 months ago

pdurbin commented 3 years ago

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:

Possible solutions:

Questions:

djbrooke commented 3 years ago
djbrooke commented 3 years ago

Possibly useful Github action:

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

donsizemore commented 3 years ago

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

pdurbin commented 3 years ago

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:

Screen Shot 2021-10-29 at 3 11 43 PM

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 commented 3 years ago

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:

poikilotherm commented 3 years ago

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 commented 3 years ago

@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 commented 3 years ago

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

pdurbin commented 3 years ago

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

poikilotherm commented 3 years ago

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

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

pdurbin commented 3 years ago

Right, right. What about https://github.com/gdcc/dvcli ? I'm just going for something you're already heavily involved in. Another idea is https://github.com/IQSS/dataverse-metrics which has releases (unlike dvcli).

poikilotherm commented 3 years ago

You might wanna play with https://github.com/poikilotherm/test-release-edit

Clone and change the release notes. Push to develop. Create a PR against develop and merge. Whatever.

As the job will create a matrix and look at multiple commits in one push, too, you should be able to edit multiple release notes in one go. But beware: currently only 1 release exists - the job checks if you edit a release note for an existing release first so no release gets created for a tag that does not exist.

Also note the repo and the job follows the same release naming mechanics as this upstream project: releases have tags in the shape of vX.Y.Z and release notes are in doc/release-notes/X.Y.Z-release-notes.md.

djbrooke commented 3 years ago

@poikilotherm thank you ! I'll check it out this afternoon.

djbrooke commented 3 years ago

Hey @poikilotherm, thanks for this. I tested it out a few ways and it does seem to work well when there are changes to develop. They get populated up to the live release notes at the conclusion of the action. This is great!

The syncing issue still persists, though. 🤔 Any updates on the live release notes are blown away when there's a merge to develop and the action runs. I guess we'll just need to decide what we're OK with - having version controlled release notes or not having to sync.

poikilotherm commented 3 years ago

Maybe I misunderstood what you peeps wanted to do 🥴

I always had the idea of using the git repo as the single source of truth and never edit a release note manually via web UI again...

It enables edits by contributors, style linting, reviews etc.

This might even involve moving the release notes to another place like the Sphinx guides (you can include Markdown there, too) and still have the release text send to the release page...

@djbrooke ping me if you want me to create a PR 😎

djbrooke commented 3 years ago

Hey @poikilotherm, I think you've got it, and you definitely solved part of the problem! I was just thinking aloud that it would be nice to keep everything in sync automatically, both ways - from the live release note to the develop branch, and from the develop branch to the live notes. I don't think there's a way to lock the live release notes from edits (except from the automated push) and if there are two versions of the notes in play it's possible that the version in Develop does not get updated, or that changes in the live notes are overwritten when updates in Develop occur. That's why I was leaning towards just having the one version post-release, even if it's not version controlled. Tough problem for sure - do you have any thoughts or examples of other projects that do this well?

pdurbin commented 3 years ago

I don't think there's a way to lock the live release notes from edits (except from the automated push)

This is the kind of feature that perhaps we could request from GitHub.

That said, I still think I'm in favor of the single live copy (nothing in git). Just for simplicity. Keep It Simple Stupid.

I'm also interested in how other projects handle release notes. It must be a common problem.

poikilotherm commented 3 years ago

@pdurbin @djbrooke there might be a way to have this two-way sync. We could trigger a job via https://docs.github.com/en/actions/learn-github-actions/events-that-trigger-workflows#release type "edited", grab the text and send a commit into develop (or create a PR). But of course this might be overkill...

I have seen some projects creating release notes, but not found any other projects with editing workflows.

That said, I still think I'm in favor of the single live copy (nothing in git). Just for simplicity. Keep It Simple Stupid.

Might be fine, although please add process documentation how people shall request edits in a way that will be clear for all participants.

pdurbin commented 2 months ago

I give up. I'm closing this issue because it's been hard to get people to care about it.

In practice, I try to keep the live release notes accurate.

I let the version in git get out date because you should be reading the live version.

Lately, I've been thinking we should move our release notes into the guides. They could be subpages of https://guides.dataverse.org/en/6.3/installation/upgrading.html . Worth a shot, maybe.