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.
Issues #123, #456
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.
A good commit message should basically answer three questions about a patch:
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=onelineshows a terse history mapping containing the commit id and the summary
git rebase –interactiveprovides 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
Remember to always add a blank line between Summary and Description.
git logdoesn’t do any special special wrapping of the commit messages.
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 –stdoutgenerates emails from commits using the Description for the message body.
$ 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
Bug[s]|Issue[s]|Report[s] IssueList– reference the listed issue(s), e.g
Fix[ed|es]|Resolve[d|s] IssueList– reference and automatically resolve the listed issue(s), e.g.
Fixes #1234, #5678
git commit –author=, or at least name the person in the text.
*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 <firstname.lastname@example.org>
These guidelines were mainly inspired by
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/