Allow the usage of git-trailers for changelog messages and security i…

…ssues

CONTRIBUTING.md

@@ -4,6 +4,95 @@ Thank you for taking the time to contribute to Matrix!
 
 This is the repository for Vodozemac, a Rust implementation of Olm and Megolm.
 
+# 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 messages should be formatted as Conventional Commits. In addition, some
+git trailers are supported and have special meaning (see below).
+
+### Conventional Commits
+
+Conventional Commits are structured as follows:
+
+```
+<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.
+
+
+#### 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: 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.
+```
+
 ## Sign off
 
 We ask that everybody who contributes to this project signs off their

cliff.toml

@@ -17,7 +17,27 @@ body = """
 {% for group, commits in commits | group_by(attribute="group") %}
     ### {{ group | upper_first }}
     {% for commit in commits %}
-        - {% if commit.breaking %}[**breaking**] {% endif %}{{ commit.message | upper_first }}\
+        {% 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 == "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/vodozemac/security/advisories/{{ github_advisory }}){% endif -%}
+              )
+          {% endif -%}
     {% endfor %}
 {% endfor %}\n
 """
@@ -39,16 +59,18 @@ commit_preprocessors = [
 ]
 # regex for parsing and grouping commits
 commit_parsers = [
-    { message = ".*[sS]ecurity", group = "Security"},
+    { 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 = "^style", group = "Styling"},
-    { message = "^test", group = "Testing"},
     { 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