Refine, document release process

[ferdnyc]

Describe your request

I've just merged the PRs adding GNOME 47 compatibility and v58 release details to the repo.

But now there's the process of actually releasing v58.

We have a bare-bones RELEASE_CHECKLIST.md file to follow, though it's somewhat out of date. (meson test no longer works since the GNOME 46 / ESM changes.)

But beyond that, @daniellandau seems to have a defined format for each of the Releases. If that's generated by a script or tool (which appears to be the case?), then it isn't part of the repo. And we don't seem to have documented it anywhere.

Proposed solution

We should probably make sure that all tools needed to maintain the repo are part of the repo, and also that processes are documented so that, as said in #1860 (comment), "others can do a release here too".

In the meantime, as I don't feel like reinventing any wheels, I'll probably just tag the v58 commit and use a relatively-barebones release "announcement" for the moment.

Alternatives

No response

GSConnect version

58

Installed from

GitHub releases (zip file)

GNOME Shell version

47

Linux distribution/release

No response

Additional context

No response

[ferdnyc]

So, turns out the tool in question is mostly just the "Generate Release Notes" button GitHub provides on the release-authoring page. Good to know. (And better to document.)

[andyholmes]

The EGO password will probably need to be with one person, since we don't have any "group"/"organization" infrastructure there (i.e. single password, single email for reset).

That being said, some folks have setup GitHub actions that can push a release to EGO. It probably would be a bit of work, but a release-on-tag setup is probably possible (as long as it doesn't upload per-commit).

[ferdnyc]

@andyholmes Honestly I wasn't even thinking about e.g.o — I've accepted that the submission process there is restricted to the designated "owner" of the app. Plus, I created issue #1880 about the need to submit the new release and @daniellandau had it submitted, published, and live on the extension page just under 2 hours later. IOW, so far that part of the process hasn't had any delays or speedbumps.

This is more concerned about the process of creating the ("official") release package for publication to https://github.com/GSConnect/gnome-shell-extension-gsconnect/releases/, and which then gets submitted to e.g.o by the Owner Of Record™. Those steps, others of us can pitch in on — but only if there's up-to-date documentation on how.

(Given that I discovered that the release-notes-generation tool is built into the GitHub web interface itself, it appears updated documentation is the only thing needed — there aren't any missing tools or whatever, as I'd originally assumed.)

[daniellandau]

So, turns out the tool in question is mostly just the "Generate Release Notes" button GitHub provides on the release-authoring page. Good to know. (And better to document.)

Yes that is the case. I used to write them on my own, which lead to me putting off doing it so I've standardized on very lightly edited github generated release notes. Also the github tool didn't even exist when I was doing my first releases of gsconnect, if I remember correctly.

(Given that I discovered that the release-notes-generation tool is built into the GitHub web interface itself, it appears updated documentation is the only thing needed — there aren't any missing tools or whatever, as I'd originally assumed.)

Yes, documentation would be good to update. You notice the button when you go to do it, but you don't really know that the button exists before trying.

My e.g.o account also publishes my personally maintained extension, so while I trust you to not do anything bad with that, it's still not The Right Way™ to do things to share that password. Uploading to e.g.o isn't much work though, and I could do it this time on my phone in a few minutes, so for me it's fine to be the human CI system doing it, no matter how busy I'm with work and family as has been the case for a while now.

[ferdnyc]

Yes, documentation would be good to update. You notice the button when you go to do it, but you don't really know that the button exists before trying.

Just so. I created this issue originally before I'd started the process at "Draft a new release". Once you're there, you see the button, and once you click it the rest of the process becomes pretty obvious, but you're blind going in without some hints as to what to look for.

I used to write them on my own, which lead to me putting off doing it so I've standardized on very lightly edited github generated release notes.

*nod* Even though I was inventing on the fly, I pretty quickly hit on what seemed the "obvious" approach, which ended up being:

1. Have GitHub generate its standard template notes
2. Edit out any "What's Changed" list entries not relevant to the users, which ended up being...
   1. Purely automated PRs (dependabot, Crowdin syncs¹)
   2. Housekeeping PRs (CI or REUSE changes — though not updates to licensing itself, those I kept)
   3. Anything else that affected the repo, but not the extension
3. (Optional) Write an introductory "What's New" summary

Which, if it largely matches your own process, I'll codify into the RELEASE_CHECKLIST.md as at least a suggestion for how someone can go about drafting a new release. Not that anyone doing so can't feel free to adjust as they see fit, but it's good to have a starting point. (One of Wikipedia's policies (!) is "ignore all rules", but that doesn't stop them from having an awful lot of rules, after all.)

My e.g.o account also publishes my personally maintained extension, so while I trust you to not do anything bad with that, it's still not The Right Way™ to do things to share that password.

1000% agreed. As long as e.g.o lists GSConnect as "[published] by dlandau", it's not (IMHO) appropriate for those submissions to be performed by others, even in an automated fashion.

While I'm sure there are extension authors who've automated their submissions, I suspect in most of those cases it's because they also have sole control of the repo where the automation is run. Most extensions do seem to be one-person shows, for the most part. AFAICT GSConnect has one of, if not the, largest teams of committers behind it (with a whopping 4 people), so we're kind of testing the limits of e.g.o's existing systems/processes.

Notes

1. Not that translation updates aren't relevant, and it'd be great to credit our translators for the work they put in. But listing the Crowdin PRs doesn't accomplish that, because they all have the same generic title and the authors of the translations aren't attributed. So they end up being noise.

[daniellandau]

Which, if it largely matches your own process, I'll codify into the RELEASE_CHECKLIST.md

Yes, sounds good