From 176fb318ccce66df5bfd53038dc49014c23bdbb8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Damir=20Jeli=C4=87?= <poljar@termina.org.uk>
Date: Wed, 9 Oct 2024 12:23:23 +0200
Subject: [PATCH] Document the new release process

---
 RELEASE.md   | 21 ---------------------
 RELEASING.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 47 insertions(+), 21 deletions(-)
 delete mode 100644 RELEASE.md
 create mode 100644 RELEASING.md

diff --git a/RELEASE.md b/RELEASE.md
deleted file mode 100644
index 25a486e9e29..00000000000
--- a/RELEASE.md
+++ /dev/null
@@ -1,21 +0,0 @@
-# Releasing `matrix-rust-sdk`
-
-- Make sure to bump all the crates to *the same version number*, and commit that (along with the
-  changes to the `Cargo.lock` file).
-- Create a `git tag` for the current version, following the format `major.minor.patch`, e.g. `0.7.0`.
-- Push the tag: `git push origin 0.7.0`
-- Publish all the crates, in topological order of the dependency tree:
-
-```
-cargo publish -p matrix-sdk-test-macros
-cargo publish -p matrix-sdk-test
-cargo publish -p matrix-sdk-common
-cargo publish -p matrix-sdk-qrcode
-cargo publish -p matrix-sdk-store-encryption
-cargo publish -p matrix-sdk-crypto
-cargo publish -p matrix-sdk-base
-cargo publish -p matrix-sdk-sqlite
-cargo publish -p matrix-sdk-indexeddb
-cargo publish -p matrix-sdk
-cargo publish -p matrix-sdk-ui
-```
diff --git a/RELEASING.md b/RELEASING.md
new file mode 100644
index 00000000000..fadd5b76aae
--- /dev/null
+++ b/RELEASING.md
@@ -0,0 +1,47 @@
+# Releasing and publishing the SDK
+
+While the release process can be handled manually, `cargo-release` has been
+configured to make it more convenient.
+
+By default, [`cargo-release`](https://github.com/crate-ci/cargo-release) assumes
+that no pull request is required to cut a release. However, since the SDK
+repo is set up so that each push requires a pull request, we need to slightly
+deviate from the default workflow. A `cargo-xtask` has been created to make the
+process as smooth as possible.
+
+The procedure is as follows:
+
+1. Switch to a release branch:
+
+  ```bash
+  git switch -c release-x.y.z
+  ```
+
+2. Prepare the release. This will update the `README.md`, prepend the `CHANGELOG.md`
+   file using `git cliff`, and bump the version in the `Cargo.toml` file.
+
+```bash
+cargo xtask release prepare --execute minor|patch|rc
+```
+
+3. Double-check and edit the `CHANGELOG.md` and `README.md` if necessary. Once you are
+   satisfied, push the branch and open a PR.
+
+```bash
+git push --set-upstream origin/release-x.y.z
+```
+
+4. Pass the review and merge the branch as you would with any other branch.
+
+5. Create tags for your new release, publish the release on crates.io and push
+   the tags:
+
+```bash
+# Switch to main first.
+git switch main
+# Pull in the now-merged release commit(s).
+git pull
+# Create tags, publish the release on crates.io, and push the tags.
+cargo xtask release publish --execute
+```
+For more information on cargo-release: https://github.com/crate-ci/cargo-release