When you're ready to commit, be sure to write a Good Commit Message™. What's in a Good Commit Message™?

We follow most general engineering best practices from other projects using Git. Some additional guidelines specific to CockroachDB apply.

Basic guidelines

General best practices:

Specific to CockroachDB:

Table of contents

General structure of a commit message

docs: summarize changes in title, but be specific

More detailed explanatory text, if necessary. The blank line 
separating the summary from the body is critical; various tools
like `log`, `shortlog` and `rebase` can get confused if you run
the two together.

Wrap the body to a fixed width consistent with the rest of the
git history.

Explain how the code was, before your change.
Explain the problem that this commit is solving. 
Explain why the problem is important to solve.
Explain (briefly) what the new situation looks like. No need
to explain the mechanism in detail: the code and comments
should explain that already.

Are there side effects or other unintuitive consequences of this
change? Here's the place to explain them.

Further paragraphs come after blank lines.

 - Bullet points are okay, too
 - Typically a hyphen or asterisk is used for the bullet, preceded
   by a single space, with blank lines in between, but conventions
   vary here

Prefer imperative voice for the subject, and declarative
(descriptive) voice for the body and release note.

If there are related issues, mention them in the commit message:

Resolves: #123
(this auto-closes the issue when the PR is merged)

See also: #456, #789
(this just cross-references the PR with the issues)

Release note (general change): The release note should outline
what changed, how a user can see what changed, and why it was
important / what the impact is. For bug fixes, it should
also explain the symptoms of the bug pre-fix and which versions
are affected. It should remain concise.

A release note can contain multiple paragraphs. This is useful to
e.g. provide examples. However it does imply the release note text
must appear after the detailed explanation, otherwise the
detailed explanation will be considered part of the release note.

Release note (general change): if there are multiple release notes,
each of them should start with its own "Release note" prefix.

See further release note examples and guidelines.

Commit title

The first line of the commit message is the commit title.

Commit description

Chris Beams: A well-crafted Git commit message is the best way to communicate context about a change to fellow developers (and indeed to their future selves). A diff will tell you what changed, but only the commit message can properly tell you why. Peter Hutterer makes this point well:

Re-establishing the context of a piece of code is wasteful. We can’t avoid it completely, so our efforts should go to reducing it [as much] as possible. Commit messages can do exactly that and as a result, a commit message shows whether a developer is a good collaborator.

How to write a good commit description

Pay attention to

OpenStack's chapter Information in commit messages:

CockroachDB-specific guidelines

How others do it