docs(dev-infra): define stricter commit message guidelines (#1410)

This change provides guidelines for writing conventional commit
messages, which will be enforced in the future. This change is being
made in order to improve ergonomics for browsing the repository and its
changes, and to support better changelog generation.

Change-Id: I533ca3c66e697aaafcc1409711600017006e264a

1 files changed, 141 insertions, 0 deletions

diff --git a/doc/contrib/commit-message-guidelines.md b/doc/contrib/commit-message-guidelines.md
new file mode 100644
index 000000000..c17e67b1a
--- /dev/null
+++ b/doc/contrib/commit-message-guidelines.md
@@ -0,0 +1,141 @@
+# Commit message guidelines
+
+We have very strict rules over how commit messages must be formatted. This
+format leads to easier to read commit history, and makes it possible to generate
+a changelog for releases.
+
+<!-- mdformat-toc start --slug=github --maxlevel=4 --minlevel=2 -->
+
+- [Specification](#specification)
+  - [Type (required)](#type-required)
+  - [Scope (optional)](#scope-optional)
+  - [Subject (required)](#subject-required)
+  - [Body (optional)](#body-optional)
+  - [Footer (optional, conditionally required)](#footer-optional-conditionally-required)
+    - [Breaking changes](#breaking-changes)
+
+<!-- mdformat-toc end -->
+
+## Specification<a name="specification"></a>
+
+Commit subjects and messages should follow the conventional commit message
+specification [version `1.0.0`][cc-1.0.0].
+
+```
+<type>[optional scope][!]: <subject>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+### Type (required)<a name="type-required"></a>
+
+Valid values for `type` MUST be one of the following:
+
+| Type       | Description                                          |
+| ---------- | ---------------------------------------------------- |
+| `build`    | Changes that affect the build system or dependencies |
+| `ci`       | Changes to the CI configuration files                |
+| `docs`     | Changes consisting only of documentation changes     |
+| `feat`     | A new feature                                        |
+| `fix`      | A bug fix                                            |
+| `perf`     | Changes that improve performance                     |
+| `refactor` | A change that neither fixes a bug or adds a feature  |
+| `test`     | Adding missing tests or correcting existing tests    |
+
+### Scope (optional)<a name="scope-optional"></a>
+
+If the scope is provided, it should be the app or package name as it would be
+perceived by a person reading the changelog.
+
+The following scopes are supported:
+
+- `api`
+- `bridge`
+- `bridge/github`
+- `bridge/gitlab`
+- `bridge/jira`
+- `bugs`
+- `cli`
+- `config`
+- `core`
+- `git`
+- `tui`
+- `web`
+
+The following additional _special scopes_, which do not relate to any internal
+package, are supported:
+
+- `changelog` used for changes to `//:CHANGELOG.md` and changelog generation
+- `dev-infra` used for changes under `//tools` or dev shell configuration
+
+### Subject (required)<a name="subject-required"></a>
+
+The subject should contain a succinct, descriptive summary of the change.
+
+- Use the imperative, present tense: "change" not "changed" or "changes"
+- Do not use capital letters, except in acronyms (like `HTTP`)
+- Do not end the subject with a `.` or `?` or any similar end-of-sentence symbol
+
+### Body (optional)<a name="body-optional"></a>
+
+The body is used to provide additional context: the _what_, _why_, and _how_ for
+the change. Just as in the **subject**, use the imperative tense. The body
+should contain the motivation for the change, and contrast it with the previous
+behavior.
+
+### Footer (optional, conditionally required)<a name="footer-optional-conditionally-required"></a>
+
+The footer should contain any information about **breaking changes** and is also
+the place to reference issues that the change closes.
+
+#### Breaking changes<a name="breaking-changes"></a>
+
+To indicate that a commit introduces a breaking change, append `!` after the
+type or scope. You can optionally provide additional information (for example,
+migration instructions) by adding a `BREAKING-CHANGE` trailer to the footer.
+This additional information will be shown in the changelog.
+
+> [!NOTE]
+> Breaking changes in this repository **always require** the `!` suffix.
+
+**Examples**
+
+Below are commit message examples you can use as references for writing a commit
+message for a breaking change.
+
+**Unscoped breaking change without additional information**
+
+```
+feat!: remove the ABC bridge
+```
+
+**Scoped breaking change without additional information**
+
+```
+feat(config)!: remove configuration option: foo.bar
+```
+
+**Scoped breaking change with additional information**
+
+```
+feat(config)!: remove option: foo.bar
+
+BREAKING-CHANGE: Users should migrate to `bar.baz`
+```
+
+**Scoped breaking change with multiple lines**
+
+If your breaking change description spans multiple lines, be sure to indent each
+subsequent line with at least one space so that the message is parsed correctly.
+
+```
+feat(config)!: remove option: foo.bar
+
+BREAKING-CHANGE: Users should migrate to `bar.baz` in order to continue
+ operating the tool and avoid a parsing error when the configuration is loaded,
+ which would throw an error stating that the `foo.bar` option doesn't exist.
+```
+
+[cc-1.0.0]: https://www.conventionalcommits.org/en/v1.0.0/#specification