A Release Process

CONTRIBUTING.md

@@ -29,43 +29,110 @@ integration tests that need a running synapse instance. These tests reside in
 [README](./testing/matrix-sdk-integration-testing/README.md) to easily set up a
 synapse for testing purposes.
 
-## Commit messages and PR title guidelines
 
-Ideally, a PR should have a *proper title*, with *atomic logical commits*, and each commit
-should have a *good commit message*.
+## Pull requests
 
-An *atomic logical commit* is one that is ideally small, can be compiled in isolation, and passes
-tests. This is useful to make the review process easier (help your reviewer), but also when running
-bisections, helping identifying which commit introduced a regression.
+Ideally, a PR should have a *proper title*, with *atomic logical commits*, and
+each commit should have a *good commit message*.
 
-A *good commit message* should be composed of:
+A *proper PR title* would be a one-liner summary of the changes in the PR,
+following the same guidelines of a good commit message, including the
+area/feature prefix. Something like `FFI: Allow logs files to be pruned.` would
+be a good PR title.
 
-- a prefix to indicate which area/feature is related by the commit
-- a short description that would give sufficient context for a reviewer to guess what the commit is
-  about.
+(An additional bad example of a bad PR title would be `mynickname/branch name`,
+that is, just the branch name.)
 
-Examples of commit messages that aren't so useful:
+# Writing changelog entries
 
-- “add new method“
-- “enhance performance“
-- “fix receipts“
+We aim to maintain clear and informative changelogs that accurately reflect the
+changes in our project. This guide will help you write useful changelog entries
+using git-cliff, which fetches changelog entries from commit messages.
 
-Examples of good commit messages:
+## Commit message format
 
-- “ffi: Add new method `frobnicate_the_foos`”
-- “indexeddb: Break up the request inside `get_inbound_group_sessions`”
-- “read_receipts: Store receipts locally, fixing #12345”
+Commit messages should be formatted as Conventional Commits. In addition, some
+git trailers are supported and have special meaning (see below).
 
-A *proper PR title* would be a one-liner summary of the changes in the PR, following the
-same guidelines of a good commit message, including the area/feature prefix. Something like
-`FFI: Allow logs files to be pruned.` would be a good PR title.
+### Conventional commits
 
-(An additional bad example of a bad PR title would be `mynickname/branch name`, that is, just the
-branch name.)
+Conventional Commits are structured as follows:
 
-Having good commit messages and PR titles also helps with reviews, scanning the `git log` of
-the project, and writing the [*This week in
-Matrix*](https://matrix.org/category/this-week-in-matrix/) updates for the SDK.
+```
+<type>(<scope>): <short summary>
+```
+
+The type of changes which will be included in changelogs is one of the following:
+
+* `feat`: A new feature
+* `fix`: A bug fix
+* `doc`: Documentation changes
+* `refactor`: Code refactoring
+* `perf`: Performance improvements
+* `ci`: Changes to CI configuration files and scripts
+
+The scope is optional and can specify the area of the codebase affected (e.g.,
+olm, cipher).
+
+### Changelog trailer
+
+In addition to the Conventional Commit format, you can use the `Changelog` git
+trailer to specify the changelog message explicitly. When that trailer is
+present, its value will be used as the changelog entry instead of the commit's
+leading line. The `Breaking-Change` git trailer can be used in a similar manner
+if the changelog entry should be marked as a breaking change.
+
+
+#### Example commit message
+
+```
+feat: Add a method to encode Ed25519 public keys to Base64
+
+This patch adds the `Ed25519PublicKey::to_base64()` method, which allows us to
+stringify Ed25519 and thus present them to users. It's also commonly used when
+Ed25519 keys need to be inserted into JSON.
+
+Changelog: Added the `Ed25519PublicKey::to_base64()` method which can be used to
+stringify the Ed25519 public key.
+```
+
+In this commit message, the content specified in the `Changelog` trailer will be
+used for the changelog entry.
+
+### Security fixes
+
+Commits addressing security vulnerabilities must include specific trailers for
+vulnerability metadata. These commits are required to include at least the
+`Security-Impact` trailer to indicate that the commit is a security fix.
+
+Security issues have some additional git-trailers:
+
+* `Security-Impact`: The magnitude of harm that can be expected, i.e. low/moderate/high/critical.
+* `CVE`: The CVE that was assigned to this issue.
+* `GitHub-Advisory`: The GitHub advisory identifier.
+
+Example:
+
+```
+fix(crypto): Use a constant-time Base64 encoder for secret key material
+
+This patch fixes a security issue around a side-channel vulnerability[1]
+when decoding secret key material using Base64.
+
+In some circumstances an attacker can obtain information about secret
+secret key material via a controlled-channel and side-channel attack.
+
+This patch avoids the side-channel by switching to the base64ct crate
+for the encoding, and more importantly, the decoding of secret key
+material.
+
+Security-Impact: Low
+CVE: CVE-2024-40640
+GitHub-Advisory: GHSA-j8cm-g7r6-hfpq
+
+Changelog: Use a constant-time Base64 encoder for secret key material
+to mitigate side-channel attacks leaking secret key material.
+```
 
 ## Review process
 

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

benchmarks/Cargo.toml

@@ -36,3 +36,6 @@ harness = false
 [[bench]]
 name = "room_bench"
 harness = false
+
+[package.metadata.release]
+release = false

bindings/matrix-sdk-crypto-ffi/Cargo.toml

@@ -67,3 +67,6 @@ assert_matches2 = { workspace = true }
 
 [lints]
 workspace = true
+
+[package.metadata.release]
+release = false

bindings/matrix-sdk-ffi/Cargo.toml

@@ -83,3 +83,6 @@ features = [
 
 [lints]
 workspace = true
+
+[package.metadata.release]
+release = false

cliff-weekly-report.toml

@@ -0,0 +1,47 @@
+# This git-cliff configuration file is used to generate weekly reports for This
+# Week in Matrix amongst others.
+
+[changelog]
+header = """
+# This Week in the Matrix Rust SDK ({{ now() | date(format="%Y-%m-%d") }})
+"""
+body = """
+{% for commit in commits %}
+    {% set_global commit_message = commit.message -%}
+    {% for footer in commit.footers -%}
+        {% if footer.token | lower  == "changelog" -%}
+            {% set_global commit_message = footer.value -%}
+        {% elif footer.token | lower  == "breaking-change" -%}
+            {% set_global commit_message = footer.value -%}
+        {% endif -%}
+    {% endfor -%}
+    - {{ commit_message | upper_first }}
+{% endfor %}
+"""
+trim = true
+footer = ""
+
+[git]
+conventional_commits = true
+filter_unconventional = true
+commit_preprocessors = [
+    { pattern = '\((\w+\s)?#([0-9]+)\)', replace = "([#${2}](https://github.com/matrix-org/matrix-rust-sdk/pull/${2}))"},
+]
+commit_parsers = [
+    { message = "^feat", group = "Features" },
+    { message = "^fix", group = "Bug Fixes" },
+    { message = "^doc", group = "Documentation" },
+    { message = "^perf", group = "Performance" },
+    { message = "^refactor", group = "Refactor", skip = true },
+    { message = "^chore\\(release\\): prepare for", skip = true },
+    { message = "^chore", skip = true },
+    { message = "^style", group = "Styling", skip = true },
+    { message = "^test", skip = true },
+    { message = "^ci", skip = true },
+]
+filter_commits = true
+tag_pattern = "[0-9]*"
+skip_tags = ""
+ignore_tags = ""
+date_order = false
+sort_commits = "newest"

cliff.toml

@@ -0,0 +1,89 @@
+# This git-cliff configuration file is used to generate release reports.
+
+[changelog]
+# changelog header
+header = """
+# Changelog\n
+All notable changes to this project will be documented in this file.\n
+"""
+# template for the changelog body
+# https://keats.github.io/tera/docs/
+body = """
+{% if version %}\
+    ## [{{ version | trim_start_matches(pat="v") }}] - {{ timestamp | date(format="%Y-%m-%d") }}
+{% else %}\
+    ## [unreleased]
+{% endif %}\
+{% for group, commits in commits | group_by(attribute="group") %}
+    ### {{ group | upper_first }}
+    {% for commit in commits %}
+        {% set_global commit_message = commit.message -%}
+        {% set_global breaking = commit.breaking -%}
+        {% for footer in commit.footers -%}
+            {% if footer.token | lower  == "changelog" -%}
+                {% set_global commit_message = footer.value -%}
+            {% elif footer.token | lower  == "breaking-change" -%}
+                {% set_global commit_message = footer.value -%}
+            {% elif footer.token | lower == "security-impact" -%}
+                {% set_global security_impact = footer.value -%}
+            {% elif footer.token | lower == "cve" -%}
+                {% set_global cve = footer.value -%}
+            {% elif footer.token | lower == "github-advisory" -%}
+                {% set_global github_advisory = footer.value -%}
+            {% endif -%}
+        {% endfor -%}
+        - {% if breaking %}[**breaking**] {% endif %}{{ commit_message | upper_first }}
+          {% if security_impact -%}
+              (\
+              *{{ security_impact | upper_first }}*\
+              {% if cve -%}, [{{ cve | upper }}](https://www.cve.org/CVERecord?id={{ cve }}){% endif -%}\
+              {% if github_advisory -%}, [{{ github_advisory | upper }}](https://github.com/matrix-org/matrix-rust-sdk/security/advisories/{{ github_advisory }}){% endif -%}
+              )
+          {% endif -%}
+    {% endfor %}
+{% endfor %}\n
+"""
+# remove the leading and trailing whitespace from the template
+trim = true
+# changelog footer
+footer = """
+<!-- generated by git-cliff -->
+"""
+
+[git]
+# parse the commits based on https://www.conventionalcommits.org
+conventional_commits = true
+# filter out the commits that are not conventional
+filter_unconventional = true
+# regex for preprocessing the commit messages
+commit_preprocessors = [
+    { pattern = '\((\w+\s)?#([0-9]+)\)', replace = "([#${2}](https://github.com/matrix-org/matrix-rust-sdk/pull/${2}))"},
+]
+# regex for parsing and grouping commits
+commit_parsers = [
+    { footer = "Security-Impact:", group = "Security" },
+    { footer = "CVE:", group = "Security" },
+    { footer = "GitHub-Advisory:", group = "Security" },
+    { message = "^feat", group = "Features" },
+    { message = "^fix", group = "Bug Fixes" },
+    { message = "^doc", group = "Documentation" },
+    { message = "^perf", group = "Performance" },
+    { message = "^refactor", group = "Refactor" },
+    { message = "^chore\\(release\\): prepare for", skip = true },
+    { message = "^chore", skip = true },
+    { message = "^style", group = "Styling", skip = true },
+    { message = "^test", skip = true },
+    { message = "^ci", skip = true },
+]
+# filter out the commits that are not matched by commit parsers
+filter_commits = true
+# glob pattern for matching git tags
+tag_pattern = "[0-9]*"
+# regex for skipping tags
+skip_tags = ""
+# regex for ignoring tags
+ignore_tags = ""
+# sort the tags chronologically
+date_order = false
+# sort the commits inside sections by oldest/newest order
+sort_commits = "oldest"

crates/matrix-sdk-base/CHANGELOG.md

@@ -1,3 +1,7 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
 # unreleased
 
 - Add `BaseClient::room_key_recipient_strategy` field

crates/matrix-sdk-common/CHANGELOG.md

@@ -0,0 +1,4 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+

crates/matrix-sdk-indexeddb/CHANGELOG.md

@@ -1,3 +1,7 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
 # UNRELEASED
 
 - Improve the efficiency of objects stored in the crypto store.

crates/matrix-sdk-qrcode/CHANGELOG.md

@@ -0,0 +1,4 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+

crates/matrix-sdk-sqlite/CHANGELOG.md

@@ -0,0 +1,4 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+