From bd936650ccf44ca33cf9c8bf553fe090534d2ab3 Mon Sep 17 00:00:00 2001
From: sudoforge <no-reply@sudoforge.com>
Date: Mon, 12 May 2025 23:38:33 -0700
Subject: [PATCH] docs(dev-infra): improve commit message guidelines (#1417)
This change provides more clarity as to the type and scope requirements,
and adds in additional information with regard to hyperlinks,
appropriate trailers to
use in the footer, and clarifies the difference between our requirements
and the conventional commit spec v1.0.0.
Change-Id: I7e3d4646c09728acf27c4efce24655896b8513a7
---
doc/contrib/commit-message-guidelines.md | 89 +++++++++++++++++++-----
1 file changed, 73 insertions(+), 16 deletions(-)
diff --git a/doc/contrib/commit-message-guidelines.md b/doc/contrib/commit-message-guidelines.md
index c17e67b1..e56b22e8 100644
--- a/doc/contrib/commit-message-guidelines.md
+++ b/doc/contrib/commit-message-guidelines.md
@@ -7,10 +7,12 @@ a changelog for releases.
<!-- mdformat-toc start --slug=github --maxlevel=4 --minlevel=2 -->
- [Specification](#specification)
+ - [Format overview](#format-overview)
- [Type (required)](#type-required)
- [Scope (optional)](#scope-optional)
- [Subject (required)](#subject-required)
- [Body (optional)](#body-optional)
+ - [Anchors / Hyperlinks](#anchors--hyperlinks)
- [Footer (optional, conditionally required)](#footer-optional-conditionally-required)
- [Breaking changes](#breaking-changes)
@@ -18,11 +20,22 @@ a changelog for releases.
## Specification<a name="specification"></a>
-Commit subjects and messages should follow the conventional commit message
-specification [version `1.0.0`][cc-1.0.0].
+Commit subjects and messages should follow the format specified below, which is
+a superset of the conventional commits specification
+[version `1.0.0`][cc-1.0.0].
+
+**A superset? What's different?**
+
+We require just one small change from the spec:
+
+- Appending the type and scope with `!` is _always_ required for breaking
+ changes. This is done by improve visibility of breaking changes in the commit
+ log.
+
+### Format overview<a name="format-overview"></a>
```
-<type>[optional scope][!]: <subject>
+<type>[scope][!]: <subject>
[optional body]
@@ -46,8 +59,8 @@ Valid values for `type` MUST be one of the following:
### 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 scope should be the app or package name as it would be perceived by a person
+reading the changelog.
The following scopes are supported:
@@ -57,18 +70,20 @@ The following scopes are supported:
- `bridge/gitlab`
- `bridge/jira`
- `bugs`
+- `cache`
- `cli`
- `config`
-- `core`
- `git`
- `tui`
- `web`
-The following additional _special scopes_, which do not relate to any internal
-package, are supported:
+There are a few exceptions to the "use the package name" rule:
-- `changelog` used for changes to `//:CHANGELOG.md` and changelog generation
-- `dev-infra` used for changes under `//tools` or dev shell configuration
+- `changelog`: used for changes related to the changelog or its generation
+- `dev-infra`: used for developer-centric changes (docs, scripts, tools, etc)
+- `treewide`: used for repo-wide changes (e.g. bulk formatting, refactoring)
+- _none / unset_: useful for `build`, `ci`, and `test` (if changing a test lib,
+ or multiple tests)
### Subject (required)<a name="subject-required"></a>
@@ -85,20 +100,62 @@ 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.
+#### Anchors / Hyperlinks<a name="anchors--hyperlinks"></a>
+
+If you include anchors, otherwise known as hyperlinks (or just "links") in the
+body, be sure to use the _reference style_ for anchor links.
+
+**Incorrect - do not use inline links**
+
+```
+Lorem ipsum dolar [sit amet](https://foo.com), consectetur adipiscing elit. In
+hendrerit orci et risus vehicula venenatis.
+```
+
+**Correct - use reference style links**
+
+Both of the below examples are valid.
+
+```
+Lorem ipsum dolar [sit amet][0], consectetur adipiscing elit. In hendrerit orci
+et risus vehicula venenatis.
+
+[0]: https://foo.com
+```
+
+```
+Lorem ipsum dolar sit amet [0], consectetur adipiscing elit. In hendrerit orci
+et risus vehicula venenatis.
+
+[0]: https://foo.com
+```
+
### 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.
+The footer should contain any information about **breaking changes** (see below)
+and is also the place to reference issues that the change closes, if any.
+
+**Examples**
+
+```
+Closes: #000
+Closes: git-bug/git-bug#000
+Fixes: #000
+Ref: https://domain.com/some-page/foo/bar
+Ref: https://github.com/git-bug/git-bug/discussions/000
+```
#### 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.
+type and scope (**this is required**). 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.
+> Breaking changes in this repository **always require** the `!` suffix in order
+> to improve visibility of breaking changes in the commit log.
**Examples**
--
GitLab