@@ -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**