Git Commit Messages

This document provides guidelines on how to write a well-formed commit message when developing for MantisBT.

See Details and explanations section below for further information.

1. Summary
   • Maximum length 72 characters, try to stay under 50 if possible.
   • Describe the change in the patch, not the bug or effects/benefits.
   • No trailing period.
2. Description
   • Optional if the Summary is self explanatory
   • Always add a blank line between summary and description
   • Wrap lines at 72 characters
   • Background information and details on the change (i.e why, how, references, etc)
   • Description must be understandable for everyone
3. Bug reference
   • Optional, but most commits should reference an issue in the bugtracker, formatted for use by the Source Integration plugin
     e.g. Fixes #1234, Issues #123, #456
4. Sign-off if the commit's author is not a MantisBT core developer

This is somewhat out of scope of this document, but nevertheless related information, so here goes.

Remember that each commit should cover only one single logical/functional change.

DO NOT

• Mix whitespace changes with functional code changes
  The whitespace changes will obscure the important functional changes, making it harder for a reviewer to correctly determine whether the change is correct.
  Solution: Create 2 commits, first one with the whitespace changes, then one with the functional changes.
• Mix two unrelated functional changes
  Again the reviewer will find it harder to identify flaws if two unrelated changes are mixed together. If it becomes necessary to later revert a broken commit, the two unrelated changes will need to be untangled, with further risk of bug creation.
• Bundle large new features in a single giant commit
  If a code change can be broken down into a sequence of patches/commits, then it should be split (e.g. commits with API changes, then commits with GUI).

A good commit message should basically answer three questions about a patch:

1. Why is it necessary?
   It may fix a bug, it may add a feature, it may improve performance, reliabilty, stability, or just be a change for the sake of correctness.
2. How does it address the issue?
   For short obvious patches this part can be omitted, but it should be a high level description of what the approach was.
3. What effects does the patch have?
   (In addition to the obvious ones, this may include benchmarks, side effects, etc.)

The Summary line is used all over Git, oftentimes in truncated form if it is too long. It should be kept under 50 characters if possible, but not be more than 72 characters long.

Using a long Summary may make it more difficult to understand what the commit is about when using one of the below (and other) commands.

Examples of where it ends up:

• git log –pretty=oneline shows a terse history mapping containing the commit id and the summary
• git rebase –interactive provides the summary for each commit in the editor it invokes
• git format-patch, git send-email, and related tools use it as the subject for emails
• git reflog, provides a local history intended to help recovery from stupid mistakes
• GitHub uses the summary in various places in their user interface

Remember to always add a blank line between Summary and Description.

• git log doesn’t do any special special wrapping of the commit messages.
  With the default pager of less -S, this means long lines will flow far off the edge of the screen, making them difficult to read. On an 80 column terminal, if we subtract 4 columns for the indent on the left and 4 more for symmetry on the right, we’re left with 72 columns.
• git format-patch –stdout generates emails from commits using the Description for the message body.
  Good email netiquette dictates we wrap our plain text emails such that there’s room for a few levels of nested reply indicators without overflow in an 80 column terminal.

• vi/vim

  $ git config --global core.editor "vi -c ':set textwidth=72'"

  and use the gq command to reflow the text, e.g. gqG from current line to end of file

The commit's Description should be as long as necessary, and in terms of contents, must

• provide background.
  The commit message should have a clear statement describing the original problem, providing enough background without having to read the bug ticket or rely on other external sources of information.
• describe how the original problem is being fixed.
  Do not assume the code is self-evident/self-documenting, except for most obvious typos or whitespace only commits.
• explain why a change is being made.
  describe the overall code structure, particularly for large changes, but more importantly describe the intent/motivation behind the changes.
• detail any limitations of the current code.
  If the code being changed still has future scope for improvements, or any known limitations then mention these in the commit message.
• include Bugtracker reference (Formatted for use by the Source Integration plugin).
  • Bug[s]|Issue[s]|Report[s] IssueList – reference the listed issue(s), e.g

    Issue #1234

  • Fix[ed|es]|Resolve[d|s] IssueList – reference and automatically resolve the listed issue(s), e.g.

    Fixes #1234, #5678

  • IssueList: #<issue1>[, #<issue2>…]
• add any other useful references (e.g. CVE ID, link to website, SHA ID of related commit…).
• give credit to the original author.
  Use git commit –author=, or at least name the person in the text.

• be signed off by the committer if different from author (see below)

• Separate paragraphs with 2 newlines
• Use bulleted lists if needed, with hanging indent (use hyphen - or asterisk * as bullets), add blank lines between bullets to improve clarity

  - bullet 1
  - bullet 2
    some additional text
  - bullet 3

When committing changes submitted by non-core team members, the commit must be signed off by the committer in the case of individual commits (use git commit -s). This is not necessary when merging several commits as a feature branch, as the merge commit itself will serve as sign off.

Based on model message in Tim Pope's blog post (see references).

Capitalized, short summary (50 chars or less)

More detailed explanatory text, if necessary, wrapped to 72 characters.
In some contexts, the first line is treated as the subject of an email
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);
tools like rebase can get confused if you run the two together.

Write your commit message in the imperative: "Fix bug" and not "Fixed
bug" or "Fixes bug." This convention matches up with commit messages
generated by commands like git merge and git revert.

You can have the Source Integration plugin automatically reference
mantisbt.org issues #1234, #1235 (the changeset will be linked to the
issues when pushed).

Further paragraphs come after blank lines.

- Bullet points are okay, too
- Typically a hyphen or asterisk is used for the bullet
- Add blank lines between bullets if needed for clarity
- Use a hanging indent when a bullet's text is too long to fit on a
  single line

Fixes #5678 (commit will be linked to the issue, which will be marked as
resolved when pushing the commit).

Signed-off-by: Core Developer <coredev@mantisbt.org>

These guidelines were mainly inspired by

• Tim Pope's blog post
• gnome.org's guidelines
• OpenStack's GIT Commit Good Practice
• Who-T blog on commit messages
• How to Write a Git Commit Message?

Grangeway suggested to implement a commit hook to perform validation on commit message, e.g. http://addamhardy.com/blog/2013/06/05/good-commit-messages-and-enforcing-them-with-git-hooks/