Skip to content

Git Commit Messages

Jump to bottom
kena edited this page Jan 24, 2018 · 13 revisions

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.

tl'dr:

How others do it

General structure of a commit message

docs: Summarize changes in around 50 characters or less

More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In many contexts, the first line is treated as the
subject of the commit and the rest of the text as the body. The
blank line separating the summary from the body is critical (unless
you omit the body entirely); various tools like `log`, `shortlog`
and `rebase` can get confused if you run the two together.

Explain the problem that this commit is solving. Focus on why you
are making this change as opposed to how (the code explains that).
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

If you use an issue tracker, put references to them at the bottom
of the explanatory text, like this:

Resolves: #123
See also: #456, #789

Release note (general change): the release note should highlight
what changes from a user's perspective. 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.

Commit title

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

  • Tooling around git give this line a special role. The title can be at most one line. Do not break it across multiple lines. Separate it from the next paragraph with an empty line, otherwise other tools may become confused.

  • Not every commit requires both a title and a body. Sometimes a single line is fine, especially when the change is so simple that no further context is necessary. For example:

      Fix typo in introduction to user guide

    Nothing more need be said; if the reader wonders what the typo was, she can simply take a look at the change itself.

  • Limit the commit title to 50 characters. 50 characters is not a hard limit, just a rule of thumb. Keeping subject lines at this length ensures that they are readable, and forces the author to think for a moment about the most concise way to explain what’s going on.

    Tip: If you’re having a hard time summarizing, you might be committing too many changes at once. Strive for atomic commits.

  • Do not end the title with a period. It's a title, not a sentence.

CockroachDB-specific guidelines

  • Prefix your commit subject line with the affected package, if one can easily be chosen. For example, the subject line of a commit mostly affecting the server package might read: "server: use net.Pipe instead of TCP HTTP/gRPC connections". Commits which affect many packages as a result of a shared dependency change should probably begin their subjects with the name of the shared dependency. Finally, some commits may need to affect many packages in a way which does not point to a specific package; those commits may begin with "*:" or "all:" to indicate their reach.
Clone this wiki locally