1# Commit message guidelines
  2
  3We have very strict rules over how commit messages must be formatted. This
  4format leads to easier to read commit history, and makes it possible to generate
  5a changelog for releases.
  6
  7<!-- mdformat-toc start --slug=github --maxlevel=4 --minlevel=2 -->
  8
  9- [Specification](#specification)
 10  - [Type (required)](#type-required)
 11  - [Scope (optional)](#scope-optional)
 12  - [Subject (required)](#subject-required)
 13  - [Body (optional)](#body-optional)
 14  - [Footer (optional, conditionally required)](#footer-optional-conditionally-required)
 15    - [Breaking changes](#breaking-changes)
 16
 17<!-- mdformat-toc end -->
 18
 19## Specification<a name="specification"></a>
 20
 21Commit subjects and messages should follow the conventional commit message
 22specification [version `1.0.0`][cc-1.0.0].
 23
 24```
 25<type>[optional scope][!]: <subject>
 26
 27[optional body]
 28
 29[optional footer(s)]
 30```
 31
 32### Type (required)<a name="type-required"></a>
 33
 34Valid values for `type` MUST be one of the following:
 35
 36| Type       | Description                                          |
 37| ---------- | ---------------------------------------------------- |
 38| `build`    | Changes that affect the build system or dependencies |
 39| `ci`       | Changes to the CI configuration files                |
 40| `docs`     | Changes consisting only of documentation changes     |
 41| `feat`     | A new feature                                        |
 42| `fix`      | A bug fix                                            |
 43| `perf`     | Changes that improve performance                     |
 44| `refactor` | A change that neither fixes a bug or adds a feature  |
 45| `test`     | Adding missing tests or correcting existing tests    |
 46
 47### Scope (optional)<a name="scope-optional"></a>
 48
 49If the scope is provided, it should be the app or package name as it would be
 50perceived by a person reading the changelog.
 51
 52The following scopes are supported:
 53
 54- `api`
 55- `bridge`
 56- `bridge/github`
 57- `bridge/gitlab`
 58- `bridge/jira`
 59- `bugs`
 60- `cli`
 61- `config`
 62- `core`
 63- `git`
 64- `tui`
 65- `web`
 66
 67The following additional _special scopes_, which do not relate to any internal
 68package, are supported:
 69
 70- `changelog` used for changes to `//:CHANGELOG.md` and changelog generation
 71- `dev-infra` used for changes under `//tools` or dev shell configuration
 72
 73### Subject (required)<a name="subject-required"></a>
 74
 75The subject should contain a succinct, descriptive summary of the change.
 76
 77- Use the imperative, present tense: "change" not "changed" or "changes"
 78- Do not use capital letters, except in acronyms (like `HTTP`)
 79- Do not end the subject with a `.` or `?` or any similar end-of-sentence symbol
 80
 81### Body (optional)<a name="body-optional"></a>
 82
 83The body is used to provide additional context: the _what_, _why_, and _how_ for
 84the change. Just as in the **subject**, use the imperative tense. The body
 85should contain the motivation for the change, and contrast it with the previous
 86behavior.
 87
 88### Footer (optional, conditionally required)<a name="footer-optional-conditionally-required"></a>
 89
 90The footer should contain any information about **breaking changes** and is also
 91the place to reference issues that the change closes.
 92
 93#### Breaking changes<a name="breaking-changes"></a>
 94
 95To indicate that a commit introduces a breaking change, append `!` after the
 96type or scope. You can optionally provide additional information (for example,
 97migration instructions) by adding a `BREAKING-CHANGE` trailer to the footer.
 98This additional information will be shown in the changelog.
 99
100> [!NOTE]
101> Breaking changes in this repository **always require** the `!` suffix.
102
103**Examples**
104
105Below are commit message examples you can use as references for writing a commit
106message for a breaking change.
107
108**Unscoped breaking change without additional information**
109
110```
111feat!: remove the ABC bridge
112```
113
114**Scoped breaking change without additional information**
115
116```
117feat(config)!: remove configuration option: foo.bar
118```
119
120**Scoped breaking change with additional information**
121
122```
123feat(config)!: remove option: foo.bar
124
125BREAKING-CHANGE: Users should migrate to `bar.baz`
126```
127
128**Scoped breaking change with multiple lines**
129
130If your breaking change description spans multiple lines, be sure to indent each
131subsequent line with at least one space so that the message is parsed correctly.
132
133```
134feat(config)!: remove option: foo.bar
135
136BREAKING-CHANGE: Users should migrate to `bar.baz` in order to continue
137 operating the tool and avoid a parsing error when the configuration is loaded,
138 which would throw an error stating that the `foo.bar` option doesn't exist.
139```
140
141[cc-1.0.0]: https://www.conventionalcommits.org/en/v1.0.0/#specification