Create a release process

[poljar]

It's time, I don't think we can realistically afford to not have a proper release process anymore or invent ever more complicated schemes how EW and EX can use the SDK without the SDK having proper releases.

Tasks

• [ ] Get rid of Git dependencies.
• [x] Automated changelog handling.
• [x] Create release automation.
• [x] Write a release playbook.

Get rid of Git dependencies

This one is self-explanatory, we use Git dependencies sometimes because we have to, but we'll need to put an end of this practice if we want to stick to release schedule.

We don't have many of them but some have been here for quite some time:

• [ ] ruma: https://github.com/matrix-org/matrix-rust-sdk/blob/d65e33ca6af52bbdb55e77f84bf650788486eb28/Cargo.toml#L50
• [ ] ruma-common: https://github.com/matrix-org/matrix-rust-sdk/blob/d65e33ca6af52bbdb55e77f84bf650788486eb28/Cargo.toml#L62
• [x] openidconnect: https://github.com/matrix-org/matrix-rust-sdk/blob/d65e33ca6af52bbdb55e77f84bf650788486eb28/crates/matrix-sdk/Cargo.toml#L130
  • [x] Needs https://github.com/poljar/openidconnect-rs/commit/c7e1dc31b83dd7559125984bfd36b9c0f191585e upstreamed
  • [x] Needs https://github.com/poljar/oauth2-rs/commit/f8e28ce5a7f3278ac85b8593ecdd86f2cf51fa2e upstreamed
    • https://github.com/ramosbugs/oauth2-rs/pull/280

The following list is used by the bindings and thus doesn't necessarily, need to be solved since we don't plan on releasing the bindings as a crate. The openidconnect crate could be moved to the bindings as well, since it solves a bindings-specific Send isssue:

• [ ] async-compat: https://github.com/matrix-org/matrix-rust-sdk/blob/d65e33ca6af52bbdb55e77f84bf650788486eb28/Cargo.toml#L121
• [ ] const_panic: https://github.com/matrix-org/matrix-rust-sdk/blob/d65e33ca6af52bbdb55e77f84bf650788486eb28/Cargo.toml#L122

Automated changelog handling

For changelogs I suggest we adopt git-cliff. It has support for monorepos.

The exact configuration that we're going to set up is up for discussion, though I suggest that we use the conventional commit configuration with one addition.

Add a special git trailer that contains the changelog entry. This should allow people to write longer and more detailed changelog entries.

Please note, the purpose of automated changelogs is not to generate the perfect changelog, manual edits after the changelog has been generated to improve the quality of the changelog is something we should always make time for.

Create release automation

This will need a bit of more investigation, but the gist of it is that we need to somehow do the following:

• Make it easier to do major releases as well as patch releases for security issues.
• Make it hard or impossible to do patch releases with breaking changes.

Please note, the goal of this task is not to give full control to the Github over our release process, in the end we do want to have a real human being:

1. Merge a PR that bumps the versions.
2. Create signed release tag.
3. Publish the crates to crates.io.

Release automation scripts/projects

There are a couple of existing projects which attempt to automate the release process which also include support for workspaces, there are of course a bunch of custom scripts and xtask written for this as well, some notable examples:

• cargo-release, from the author of typos-cli which we heavily use, some additional docs can be found here.
• Ruma, uses a custom xtask.
• wasmtime, uses a custom script.
• Insert you favorite example here...

Write a release playbook

Of course, all of the above should be documented and well-defined so any person in the team can do a release. Inspiration can be found in the wasmtime project.

[richvdh]

It's not my decision, so I'll bang this drum one more time and then leave it to the team to decide, but...

I still think that attempting to use commit messages to generate changelogs just gives you crap commit messages and crap changelogs. (I was inspired to blog about it, in case you're not bored of hearing from me about it yet.)

[poljar]

I still think that attempting to use commit messages to generate changelogs just gives you crap commit messages and crap changelogs. (I was inspired to blog about it, in case you're not bored of hearing from me about it yet.)

The blog post mixes the criticism of conventional commits with the criticism of git commits containing potential changelog entries.

It seems that the suggestion of the git trailer would address all of your concerns, except perhaps the git revert case?

[richvdh]

Ah, I missed the idea of a git trailer, sorry. Yeah, I think that helps a lot.

What I would say is this: I think that changelog entries ought to be reviewed just like code changes, and I think putting those changelog entries in a git commit message -- which frequently isn't even written until after a review happens -- makes that hard. I think it might also make it tricky to have CI which reminds people to write changelogs.

Perhaps I'm just making up problems though.

[poljar]

I think it might also make it tricky to have CI which reminds people to write changelogs.

Hmm, but it's similarly easy/hard to check if a changelog file has been modified or if git commits contain a specific trailer via a github action. The bigger problem is to teach a computer how to decide if a PR requires a changelog entry or not.

[bnjbvr]

The bigger problem is to teach a computer how to decide if a PR requires a changelog entry or not.

By combining cargo-public-api and cargo-insta, it's possible to:

• check in the output of cargo-public-api
• add a CI pass running cargo-insta running cargo-public-api, and comparing against the checked-in output
• if there's a mismatch, then the public API has changed

It's not precise because a public API may not change despite a breaking change (in behavior), but I think that's a good 80/20 solution to the problem of finding what requires changelog entries overall.

[bnjbvr]

Also, we chatted about when to mandate changelog entries, and there could be a simple check that if a PR changes more than N LOC (for N >= 300? 400?), then it requires a changelog entry. Would lead to false positives for sure, but it would likely be a good first approximation.

[richvdh]

(Could you default to requiring changelog entries, but provide a mechanism for an author to explicitly flag "I've thought about this, and decided it doesn't need a changelog entry?)

[poljar]

I made some git-cliff changes for vodozemac: https://github.com/matrix-org/vodozemac/pull/165.

Adding trailers for common info about security issues was nice as well.

[spantaleev]

Now that matrix.org has disabled authenticated media and other servers are doing the same, not having a matrix-rust-sdk that supports authenticated media breaks some things.

One such related issue is https://github.com/etkecc/baibot/issues/12. We have a few other features that are broken (when used against a server that disables authenticatd media) due to the latest release of matrix-rust-sdk not supporting authenticated media yet.

As a solution to our troubles, we may go with using the main version of matrix-rust-sdk, but this is inconvenient, because we need to make our underlying library (mxlink) use that version.. Doing that, we can no longer publish an mxlink crate to crates.io, nor a baibot crate. And we'd be creating more mess for everyone downstream.

---

I understand that figuring out a proper release process (and how to do changelogs.. and how to stabilize what you currently have enough to call it a "release"), but it'd be great if the matrix-rust-sdk team could soon cut an 0.8 (or whatever number) release and publish it, so others that are building upon it have a recent up-to-date foundation that doesn't choke on authenticated media, etc.

The current v0.7.1 release just seems too out-of-date now.

[poljar]

I understand that figuring out a proper release process (and how to do changelogs.. and how to stabilize what you currently have enough to call it a "release"), but it'd be great if the matrix-rust-sdk team could soon cut an 0.8 (or whatever number) release and publish it.

I understand the frustration and sympathize with it. We are in the process of finalizing things, i.e. https://github.com/matrix-org/vodozemac/pull/189 is pretty much what we will use, we just need a bit of time to port things over and get rid of the remaining git dependencies.

Hopefully we can cut a release sometime next month.

[poljar]

So a PR appeared: #4097.

[poljar]

Alright almost everything is done, only one git dep left.

The patch overrides can be left alone, though I did try to get rid of the async-compat one but complement-crypto didn't like my patch: https://github.com/matrix-org/matrix-rust-sdk/actions/runs/11180155206/job/31083265457?pr=4071.

[poljar]

So we got rid of the final git dep blocking the release with 3c484597.

The release was planned for this week but things got a bit delayed due to my wish of including #4237 in the release.

I'll close this now and we'll release next week.

[poljar]

For anyone watching this issue, a release has happened.