Apply suggestions from code review

Co-authored-by: Ivan Enderlin <[email protected]>
Signed-off-by: Damir Jelić <[email protected]>

CONTRIBUTING.md

@@ -30,18 +30,31 @@ integration tests that need a running synapse instance. These tests reside in
 synapse for testing purposes.
 
 
+## Pull requests
+
+Ideally, a PR should have a *proper title*, with *atomic logical commits*, and
+each commit should have a *good commit message*.
+
+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.
+
+(An additional bad example of a bad PR title would be `mynickname/branch name`,
+that is, just the branch name.)
+
 # Writing changelog entries
 
 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.
 
-## Commit Message Format
+## Commit message format
 
 Commit messages should be formatted as Conventional Commits. In addition, some
 git trailers are supported and have special meaning (see below).
 
-### Conventional Commits
+### Conventional commits
 
 Conventional Commits are structured as follows:
 
@@ -51,33 +64,35 @@ Conventional Commits are structured as follows:
 
 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
+* `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
+### 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.
+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
 
-#### 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
+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
+Changelog: Added the `Ed25519PublicKey::to_base64()` method which can be used to
 stringify the Ed25519 public key.
 ```
 
@@ -92,9 +107,9 @@ vulnerability metadata. These commits are required to include at least the
 
 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.
+* `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:
 

RELEASING.md

@@ -1,30 +1,30 @@
 # Releasing and publishing the SDK
 
-While the release process can be handled manually, cargo-release has been
+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
+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
-```
+  ```bash
+  git switch -c release-x.y.z
+  ```
 
-2. Prepare the release. This will update the README.md, prepend the CHANGELOG.md
+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 and README if necessary. Once you are
+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

cliff-weekly-report.toml

@@ -28,16 +28,16 @@ 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},
+    { 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]*"

cliff.toml

@@ -1,4 +1,4 @@
-# configuration file for git-cliff (0.1.0)
+# This git-cliff configuration file is used to generate release reports.
 
 [changelog]
 # changelog header
@@ -64,16 +64,16 @@ 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},
+    { 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

xtask/src/release.rs

@@ -113,8 +113,8 @@ fn prepare(version: ReleaseVersion, execute: bool) -> Result<()> {
     if execute {
         eprintln!(
             "Please double check the changelogs and edit them if necessary, \
-             publish the PR and once it merged switch to main and pull the PR \
-             and run cargo xtask release publish"
+             publish the PR, and once it's merged, switch to `main` and pull the PR \
+             and run `cargo xtask release publish`"
         );
     }