commit-message-guidelines.md

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.

Specification

Commit subjects and messages should follow the format specified below, which is a superset of the conventional commits specification version 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

<type>[scope][!]: <subject>

[optional body]

[optional footer(s)]

Type (required)

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)

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:

  • api
  • bridge
  • bridge/github
  • bridge/gitlab
  • bridge/jira
  • bugs
  • cache
  • cli
  • config
  • git
  • tui
  • web

There are a few exceptions to the "use the package name" rule:

  • 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)

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)

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.

Anchors / Hyperlinks

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

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

To indicate that a commit introduces a breaking change, append ! after the 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 in order to improve visibility of breaking changes in the commit log.

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.