Announce gitoxide releases via discussion comments

[EliahKagan]

Fixes #1311

This repository produces releases associated with all of the gitoxide-related crates: gitoxide, but also the many gix-* crates (and gitoxide-core). The narrowest readily available way to use GitHub to subscribe for notifications about releases has so far been to watch all releases (Watch → Custom, "Releases"). But this is not specific to releases associated with any particular crate.

It is possible to set up something to filter tag names, but that is inconvenient if one is not already doing similar automation. It would not integrate with ordinary uses of GitHub's web-based or emailed notifications. Furthermore, the gitoxide crate differs from the others in some important ways. One way is how, because it ships binaries, it is the crate most often packaged in downstream distributions. I believe this the main ongoing situation described in #1311.

Secondarily, but also related to ameliorating #1311, it seems to me that having an easy way to subscribe specifically to announcements for GitHub releases associated with the gitoxide crate (i.e., v* tag releases) would also make it somewhat easier for users unfamiliar with the project's structure to identify which releases are "top-level." In particular, although the main binary for gitoxide shall one day be ein, currently gix probably has the most functionality that is regularly used, and there is also a crate named gix, which is a library crate providing facilities such as Repository, and which is not the crate that carries the gix binary.

Fortunately, it is possible to allow users to subscribe to such notifications through GitHub, by having them automatically posted in a discussion created for that purpose. This pull request adds an announce-release job to the release workflow, that runs after the publish-release job and creates a discussion comment saying that the release has been created and linking to the release page for it. This is usable because:

• Discussions can be easily subscribed to and unsubscribed from individually.
• Discussions can be locked, so that only "collaborators" can post to them, so that users who subscribe to them don't get extra notifications.
• Locking a discussion does not impose any restrictions on subscribing.
• GitHub Actions jobs can post comments to discussions with the GitHub GraphQL API, if they declare discussions: write permissions.
• discussions: write permissions are automatically sufficient to post new comments even in locked threads.

It seems to me that such an automatically commented discussion thread is likely to help some downstream package maintainers, and to be of interest to some other users.

I tested this in a discussion in my fork, EliahKagan#6, which can be examined to see what the comments look like.

As for the hyperlinks in them, for releases that are actually published, the links go to the releases page. That same URL for an unpublished release goes to the tag page. This can be confirmed by comparing the URLs:

• https://github.com/EliahKagan/gitoxide/releases/tag/v0.39.0-alpha.2-DO-NOT-USE, which is associated with a draft release in my fork
• https://github.com/GitoxideLabs/gitoxide/releases/tag/v0.38.0, which is associated with a non-draft release in this upstream repository.

If this PR is to be merged, then there are three changes to this upstream repository that should also be made:

1. A new discussion should be created and given an appropriate title and brief body explaining its purpose.

   The title should not start like test, [test, or (test or any case variants: when a release seems like it is for testing releasing rather than being a "real" release, the job will refuse to post a comment about it unless the discussion is titled that way. Since this would be the "production" discussion thread, we want that refusal.

2. The new discussion should be locked. (It would be fine to allow reactions to be posted, though, since those do not generate notifications. One chooses whether to allow them when locking the discussion.)

3. A new GitHub Actions variable named RELEASE_ANNOUNCEMENTS_URL should be created, and given the full URL of the discussion as its value.

I would be able to do (1) myself and would be happy to do so, but I would not be able to do (2) or (3).

[Byron]

This is fantastic, thanks so much! I can't wait to see this in action in a couple of days!

The job is quite advanced as well and I am always impressed by the skill that enables it. Thanks to you I can't tell myself anymore that "this can't be done in shell" :D.

For completeness, here is the variable configuration to link to the release discussion, hoping that this will work.

I could have used an environment variable as well but think that these are accessed through a different prefix, so this should be correct.

[EliahKagan]

This is fantastic, thanks so much! I can't wait to see this in action in a couple of days!

Thanks! Is that to say that this PR is ready to be merged?

For completeness, here is the variable configuration to link to #1693, hoping that this will work.

Looks good. Thanks!

I could have used an environment variable as well but think that these are accessed through a different prefix, so this should be correct.

Yes, in the ${{ }} syntax and elsewhere that GitHub Actions contexts are supported (e.g., values of if keys), GitHub Actions variables are in vars, while environment variables set on that page (and some others) are in env. Or environment variables can be accessed in the environment itself, e.g. $name in a shell script.

It's possible to write a workflow that accepts a variable as being either in env or vars, such as by checking for it as an environment variable and, if absent, using it from vars to append to the file that $GITHUB_ENV expands to, then using it as an environment variable in subsequent steps. But I didn't do anything like that here: it is assumed to be a configured in the repository settings as a GitHub Actions (non-environment) variable.

[Byron]

Thanks! Is that to say that this PR is ready to be merged?

Apologies, I forgot to click the button 🤦‍♂️.

But I didn't do anything like that here: it is assumed to be a configured in the repository settings as a GitHub Actions (non-environment) variable.

Definitely no need to complicate things, I am just happy I picked the right place for the variable configuration, and will be looking forward. I also have added a paragraph about that to the upcoming report.

[EliahKagan]

I'm happy to see that the new job worked, and #1693 (comment) was posted automatically for the v0.39.0 release!

---

When checking that, I noticed that it looked like the release was publicly viewable even before all files were attached. I certainly have no objection to this, especially it was intentional. But as far as I know, it should only happen if the release is manually marked non-draft sometime between when the create-release and publish-release jobs run for it.

If nothing like that happened, then I can look into it.

[Byron]

It worked like a charm, thanks again!

Indeed, I didn't interact with the release page at all, for all I know, these have always been made public in the moment cargo smart-release uploads the changelog. It creates a release, associates it with the annotated tag it created, and uploads a markdown compatible version of the changelog.

To fix this, it might be easiest to set the release back to draft mode when the release-artifact builds are started.

[EliahKagan]

To fix this, it might be easiest to set the release back to draft mode when the release-artifact builds are started.

I don't recommend automatically setting releases back to draft, because this will be confusing to users who see a notification (in their GitHub feed or otherwise) of the release, then find that the release is gone.

Another concern is that I worry publishing and then dispublishing releases may be incompatible with some tools that might be in use to automate things in response to new releases. If the release is seen to exist, a tool may not handle its unexpected disappearance. Even if all tools are free of race conditions, they will not necessarily handle the case well by waiting or scheduling themselves to re-run; they may just report a failure and do nothing more until a user decides how to handle it. (As far as I know, users without write access to the gitoxide repository cannot even query the GitHub API in a way that distinguishes a draft release from the absence of a release.)

Instead, could cargo-smart-release create it as a draft?

If I understand correctly, its create_release function currently doesn't do this because it is used for all crates in a workspace, and most crates--at least for gitoxide--should have their releases created as non-draft.

Since cargo-smart-release is supposed to work without requiring any special configuration, specifying for each crate whether its GitHub release should be created as a draft may not be wanted. But there seem to be three most useful rules to pick from:

1. Don't create any releases as drafts. (The current rule.)
2. Create all releases as drafts.
3. Create releases as drafts when the crate being released provides no binaries for installation (i.e., provides no executable binaries other than possibly examples).

If I am right that these are the most useful rules to choose from, they could be made specifiable through command-line arguments.

The justification for (3) is that it's when a crate provides binaries that additional work often must be done to create prebuilt executables and attach them to the release.

I think it be fine even to keep the default behavior as (1), so long as an option is available to select (3), which could be used when using cargo-smart-release to release gitoxide crates.

The gitoxide crates with binary executables are:

• gitoxide, which we would want created as a draft.
• gix-testtools, for which, if I recall correctly, you have hoped to remove its main.rs, so maybe that could be done at the same time. (In those comments, I had proposed adding a subcommand in gix-testtools, but that would really be fine in internal-tools.)
• internal-tools, which is not published.
• gix-tui, which is not yet implemented.

Other things that appear in the output of find . -name main.rs are part of unit or integration tests, except gix-credentials/src/program/main.rs which, if I understand correctly, is still just a library (its main function is meant to be called from a program).

---

Edit: The other dimension of this is the question of what exactly the effect currently is of the command in this step of create-release:

gitoxide/.github/workflows/release.yml

Lines 69 to 72 in b34d14e

	- name: Create GitHub release
	run: gh release create "$VERSION" --title="$VERSION" --draft
	env:
	GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Last time I revised that part, I think I believed either that this was creating a release that did not yet exist (draft or otherwise), or that it would have no effect if a release for that tag and with that title already existed. But when the intended release already exists, I'm not sure attempting to create it again really is idempotent. Testing suggests otherwise.

Commands of that form ask questions if they think they are being run interactively. To produce a situation similar to what happens on CI, I've been running

: | gh release create v1 --title=v1 --draft

in a local clone of this repository that I use for testing. To produce a similar situation, I created a release by other means first (using the web-based interface). The release is titled v1 and at the tag v1.

Then, when I ran the above gh command, it created a draft for another release titled v1. Since it's a draft, it's only visible to me, and you won't see it on the releases page there. (I presume I can publish it, but then it would be less clear what parts of the situation were created in the experiment.) For me, the releases page on my testing hello-world repository has:

(The draft release also has an earlier date. I think that's from the commit. I'm not clear on why that happens.)

This all raises the question: does the gitoxide repository have a bunch of unpublished draft releases lying around that are named and tagged the same as actual releases? Except during the releasing process, I expect that this upstream repository does not intentionally have draft releases, so this could be examined just by looking to see if there are any. I don't think there's a way I can do this myself, since accessing draft releases requires write access to a repository, I believe that applies even to enumerating them.

I'm sure this can be done much more elegantly, but this should list them:

gh -R GitoxideLabs/gitoxide release list --json createdAt,isDraft,name,publishedAt,tagName --jq '.[] | select(.isDraft == true) | [.createdAt,.name, .publishedAt, .tagName] | @tsv'

Subsequent accesses to the release are by its name or tag name, and those will find the one that was created previously. For example, when I run gh release view v1 in my testing hello-world repository with the two v1 releases shown above, the first, non-draft one is reported. So the *-release jobs subsequent to create-release in gitoxide's release workflow should be accessing the release created initially by cargo-smart-release. Nonetheless, I think it is probably undesirable to have separate same-named same-tagged draft releases lying around indefinitely, and some future changes to the release workflow (or other operations) might inadvertently be affected by them.

[Byron]

Thank you for the exhaustive analysis!

I very much like the idea of adjusting cargo smart-release to create different kinds of releases based on crate-metadata. Even though I don't know how easy it would be to determine if there are binary artefacts or not, that condition seems to be the right one. There wouldn't be an issue in changing the default way of handling things either, and I also agree that the original behaviour should be recoverable with a new option.

Running the command-line provided here yields only a single draft release (2024-11-24T10:00:33Z v0.39.0 0001-01-01T00:00:00Z v0.39.0), but this command also shows the v0.38.0 is available as draft (note the -L1000 see everything).

gh -R GitoxideLabs/gitoxide release list -L1000 --json createdAt,isDraft,name,publishedAt,tagName --jq '.[] | select(.isDraft == true) | [.createdAt,.name, .publishedAt, .tagName] | @tsv'

So it does look like these will be piling up.

As the binaries that are produced here are mostly for debugging/developer use, I always found them secondary to the release itself. If the notification in the release thread would only be produced once all release-builds are done, then that would also serve the purpose I think.

As long as smart-release create GitHub release for each crate and users can't differentiate which tags they want to listen for, I don't think anybody will sign up for official release notifications either.
Thus, should what we have not be good enough already? It does seem like the release notification thread solves all problems :).

[EliahKagan]

I very much like the idea of adjusting cargo smart-release to create different kinds of releases based on crate-metadata. Even though I don't know how easy it would be to determine if there are binary artefacts or not, that condition seems to be the right one.

I'll open an issue on cargo-smart-release so this idea is not forgotten, and so I can share progress on figuring out how to do it (though I have no such progress yet).

Running the command-line provided here yields only a single draft release (2024-11-24T10:00:33Z v0.39.0 0001-01-01T00:00:00Z v0.39.0), but this command also shows the v0.38.0 is available as draft (note the -L1000 see everything).

Thanks, I had gotten the wrong idea that -L applied after filtering, but apparently it applies before filtering and thus has to be increased even when one knows the number of releases after filtering will be small.

So it does look like these will be piling up.

Since there are not many still-draft releases piled up so far, you could probably delete them manually if you like, such as through the web-based interface. Deleting them from using the gh tool might be slightly tricky, in that one might accidentally delete an actual (non-draft) release at the same name and tag, though I suspect there is some safe way to do that, too.

As the binaries that are produced here are mostly for debugging/developer use, I always found them secondary to the release itself.

What binary will #1238 use? I had envisioned that it would use gix until ein clone is implemented, and then use ein. (But it could use its own binary.)

If the notification in the release thread would only be produced once all release-builds are done, then that would also serve the purpose I think.

In part, yes. There are two caveats that I can think of:

• Anyone who happens to see the release before it is fully populated may be confused, due to the non-immediate changes that are made to the assets held in the release, including the removal of individual checksum files. This could be mitigated by adding, at some early point, an italicized note at the end of the displayed release notes about the release not having all its assets yet, and then removing it in the publish-release job, and/or by keeping individual checksum files (as many projects do) rather than collecting them into a single file as we have been doing.
• In #1692 (comment), I said "notification," but I actually used that word incorrectly. I meant something broader that takes place more often and potentially affects more users directly, a detailed below. In effect, I think many more people are likely to see partially populated gitoxide releases than would be predicted by considering only actual notifications.

As long as smart-release create GitHub release for each crate and users can't differentiate which tags they want to listen for, I don't think anybody will sign up for official release notifications either.

I just temporarily tried having my separate "machine account" @NeopreneSock watch this repository in two ways, where the number of watchers shown started out as 56:

• "Custom", and checking all boxes except "Releases" - the number of watchers was still shown as 56
• "All Activity" - this increased the number from 56 to 57 (until unwatching)

Based on this, I think at least 56 accounts are receiving notifications for all gitoxide tag/crate releases. (It is probably exactly 56 accounts, but it could be more if some people use a custom watch but do not uncheck "Releases".)

Thus, should what we have not be good enough already? It does seem like the release notification thread solves all problems :).

Sorry, I should not have said "notification" in #1692 (comment).

The release notification discussion thread created in this PR does solve the problem of allowing people to be notified when binary releases are ready. People who wish to watch this repository can do a custom watch with all boxes checked except the box for Releases, in which case they will not receive any misleading notifications related to releases.

However, what I meant to express in #1692 (comment) was:

I don't recommend automatically setting releases back to draft, because this will be confusing to users who see a notificationan event (in their GitHub feed or otherwise) of the release, then find that the release is gone.

That particular concern is still specific to marking published releases back to being drafts, so it's not something we have to worry about if we're not doing that.

More broadly, however, people are likely to have the new existence of a releases surfaced to them under various conditions other than subscribing for notifications, anytime they have an algorithmically curated feed, and such a feed is built into the GitHub web interface. By default, it shows events based on guessed interest, stars, and events of interest to users one follows. This can include releases (unless one customizes one's feed to not see any projects' releases). So some people are probably finding out that way about releases even before they are populated. This is part of what I had been thinking about.

I consider this a sufficient reason not to routinely mark published releases back to draft. But so long as we're not doing that, I think it's not much of a problem. Anyway, the two changes described above for how to make partially populated releases less confusing would help users who find releases through feed events, too, so long as they are not routinely dispublished. Whether those changes are worthwhile, I am not sure.

A more significant reason to prefer to start gitoxide releases (v* tag releases) out as drafts may be if the surfacing of events that I was thinking about is not happening. Recently, I have not seen releases from this repository in my feed. I think that when there is a high volume at a time, they may be less often shown. Because there is a natural delay between when gitoxide releases are initially created--as draft or not--and when they are done being populated with assets, I suspect that publishing them only once they are populated may result in knowledge of them being surfaced to more users in algorithmic feeds. That is, csr makes gitoxide releases at the same time (usually) as various other crate releases, and if gitoxide were published slightly later (by starting off as a draft) then it might be more visible.

[Byron]

Since there are not many still-draft releases piled up so far, you could probably delete them manually if you like, such as through the web-based interface. Deleting them from using the gh tool might be slightly tricky, in that one might accidentally delete an actual (non-draft) release at the same name and tag, though I suspect there is some safe way to do that, too.

It really is no problem to do that by hand, and I just removed the two drafts using the web-UI.

What binary will #1238 use? I had envisioned that it would use gix until ein clone is implemented, and then use ein. (But it could use its own binary.)

A good point, I hadn't thought about it. As the binary it uses is more of an implementation detail, it could start out using gix and move on to something ideally more stable with ein, when available.

A more significant reason to prefer to start gitoxide releases (v* tag releases) out as drafts may be if the surfacing of events that I was thinking about is not happening. Recently, I have not seen releases from this repository in my feed. I think that when there is a high volume at a time, they may be less often shown. Because there is a natural delay between when gitoxide releases are initially created--as draft or not--and when they are done being populated with assets, I suspect that publishing them only once they are populated may result in knowledge of them being surfaced to more users in algorithmic feeds. That is, csr makes gitoxide releases at the same time (usually) as various other crate releases, and if gitoxide were published slightly later (by starting off as a draft) then it might be more visible.

Thanks for elaborating, I think we are on the same page.
It seems to all come down to cargo smart-release being able to create draft releases, and/or to even avoid creating releases for tags entirley.
Somehow as simplest way to accomplish this I'd use gix-glob and say --skip-gh-release '*' and --draft-gh-release gitoxide. The arguments would have to be multi-args as globs aren't as flexible as regex, but easier to use and reason about.
With that in place, the 56 'full' subscribers won't get swamped anymore, and the initial draft status of the actual release will allow it to be filled with artefacts before it's published.

Implementing this in cargo smart-release is also no more than an exercise in clap and passing options down to where they are needed.

Thanks again for not letting go of this problem until it is resolved, it feels close and very much achievable now.

[EliahKagan]

Thanks for elaborating, I think we are on the same page. It seems to all come down to cargo smart-release being able to create draft releases, and/or to even avoid creating releases for tags entirley. Somehow as simplest way to accomplish this I'd use gix-glob and say --skip-gh-release '*' and --draft-gh-release gitoxide. The arguments would have to be multi-args as globs aren't as flexible as regex, but easier to use and reason about. With that in place, the 56 'full' subscribers won't get swamped anymore, and the initial draft status of the actual release will allow it to be filled with artefacts before it's published.

Implementing this in cargo smart-release is also no more than an exercise in clap and passing options down to where they are needed.

Thanks again for not letting go of this problem until it is resolved, it feels close and very much achievable now.

Actually, it seems to me that making GitHub releases for all versioned crates that are developed in this repository is a good thing, and I very much recommend continuing to do so.

Users who have an unfiltered watch on the repository presumably want to receive, or are at least okay with receiving, those notifications. I furthermore expect that to be more the case now that there is an alternative way (introduced in this PR) to easily subscribe to just notifications about releases of the gitoxide crate. In context, these are also probably notifications of relatively high interest, since users who have an unfiltered watch (the whole project, no boxes unchecked) will receive notifications for numerous more minor events, usually many times a day. For example, such users receive notifications for every comment posted on an issue, pull request, or discussion, unless they have muted/unsubbed from the thread.

Much more important, there are a number of benefits I think come from publishing GitHub releases for all gix-* (and gitoxide-core) crates, i.e. the library crates, in addition to the gitoxide crate:

• Whole-project release history: Release notes can be viewed in the repository itself, but I don't know of a convenient way to view releases of crates hosted in this repository, with their release notes, in the order that they occurred. Viewing individual crates' histories in isolation gives an incomplete view of the project's progress and current status. A related benefit of having GitHub releases with release notes for each recently modified crate is that it makes it easier to discover what crates are for and what kinds of new functionality and fixes they have received. To the best of my knowledge, this information is not readily accessible, about the gitoxide project as a whole, in any of the other commonly accessed places such as crates.io, docs.rs, or lib.rs, where the view is more atomized and isolated, focused on individual crates.

  It can sort of be accessed by viewing the list of all the project's tags, but those don't seem to want to sort by date and are, in any case, not sorted by date by default, and in general they are much less readable and navigable, and the information shown to be associated with existing tags cannot be changed if corrections or clarifications are needed. (It makes sense to me that it is that way, since the GitHub feature for associating rich information with tags that are judged to be significant, and allowing them to browsed in order, is Releases.)

• Security information: Except in repositories that never publish any GitHub releases for anything, it is easier to understand information in repository-level security advisories when the packages they refer to are also published as GitHub releases. At least to me, it seems unintuitive for some crates identified as the first crate with a fix to be findable on the repository's Releases page, while others are not. I would tend to assume that the fixed crates are not yet available, or otherwise to be confused. Even in the absence of confusion, being able to easily find and examine release notes for affected, fixed, and other security-relevant versions is a very useful convenience.

  To be clear, all of this is about what is useful, convenient, or clarifying for people interacting with the repository. I am not saying that GitHub advisories require GitHub releases to be published. For supported ecosystems, which includes Cargo, they integrate with the off-site registry. Neither the core functionality of advisories, nor tools that use them such as Dependabot, require GitHub Releases be used consistently or at all (they don't even use repository-local advisories). Those features will continue to work even if releases are used differently or for fewer crates.

• Continuity: Because there are already a considerable number of releases here for library crates, extra confusion is highly likely if GitHub releases for library crates are stopped: the latest available listed version of a gix-* crate is likely to be assumed to be the latest actual release of it, unless highly visible notice is given of the change. But if such notice is feasible, then it also would solve the problem of noisy notifications because it could be used to tell people who want to be notified only of gitoxide crate releases how to do that. One way confusion can occur is if users edit a release URL to put in a version they are interested in. I do this pretty often. (Of course, consistency could be achieved in the opposite way by deleting all the existing releases of library crates. But that would break numerous existing hyperlinks and cause significantly greater confusion.)

• Integrations: Even without write access to the repository or membership in GitoxideLabs, people can use releases in an automated way, not limited to anything we have set up or envisioned, to automate tasks based on whatever kind of information they want, or just to be informed of events of interest in a customized way. Although I think the API can be used for this, the main resource I want to point out is the Atom feed, https://github.com/GitoxideLabs/gitoxide/releases.atom. I don't know how many people, if anyone, are making use of this now for this repository, but it seems to me that a feed, using a standardized protocol, to be notified of releases outside of GitHub's interface or email, is valuable and may come to be of even greater interest over time.

• This is a library project: Although GitHub releases have a special use for the gitoxide crate because binaries are attached to it as assets, my understanding of both the current and intended primary use of this project is (as you mentioned above) to provide libraries for use in other programs (or other libraries). Therefore, other crates are comparably important, or more important, than the gitoxide crate.

  For this reason, having release notes and other information about them readily available, making it easy to view diffs with them as endpoints in the Compare drop-down menu, and generating notifications for them (since they are not always released at the same time as gitoxide, and when they are not it is often of note, such as in the case of a security vulnerability that does not affect, or does not warrant a new, gitoxide release, e.g., CVE-2024-40644), all seem valuable. It also seems valuable to show them just to make their importance clear and to avoid presenting the gix and ein binaries as having outsized importance.

So, that is my case for continuing the current practice of publishing GitHub Releases for the gitoxide library crates (gix-* and gitoxide-core) as well as the gitoxide binary crate.

[Byron]

Thank you for making the case so clearly!

Let's keep GitHub releases then :)! For posterity, I also state that I had no intention to stop making them either, as with the automated notification for gitoxide releases as powered by GitHub discussions, I'd think the greatest shortcoming has been addressed.

[EliahKagan]

For posterity, I also state that I had no intention to stop making them either

Ah, okay. I may have misunderstood the significance of that idea in what you were saying! Thank you for bearing with all that text anyway. And maybe it will be useful in the future if, ironically, it ever comes to be false: it could happen that future circumstances might outweigh those benefits, so perhaps having them articulated there will make it easier to tell whether that has happened.