Differences

This shows you the differences between two versions of the page.

--- mantisbt:git_commit_messages [2014/05/27 07:53] – Added Description section dregad
+++ mantisbt:git_commit_messages [2018/02/06 08:35] (current) – [Checklist] Bug reference examples dregad
@@ Line 1: / Line 1: @@
-====== Git Commit Message ======
+====== Git Commit Messages ======
 This document provides guidelines on how to write a well-formed commit message
 when developing for MantisBT.
@@ Line 9: / Line 12: @@
 ===== Checklist =====
-See below for further details
+See [[git_commit_messages#details_and_explanations|Details and explanations section below]] for further information.
   - **Summary**
@@ Line 19: / Line 22: @@
     * Always add a **blank line** between summary and description
     * Wrap lines at **72 characters**
-    * **Background** information and **details** on the change (i.e *why*, not *how*)
+    * **Background** information and **details** on the change (i.e why, how, references, etc)
-    * Description must be **understandable** for everyone, not just for you (also 6 months down the line !)
+    * Description must be **understandable** for everyone
   - **Bug reference**
-    * Optional, but most commits should reference an issue in the [[http://mantisbt.org/bugs|bugtracker]], formatted for use by the **Source Integration** plugin
+    * Optional, but most commits should reference an issue in the [[http://mantisbt.org/bugs|bugtracker]], formatted for use by the **Source Integration** plugin \\ e.g. ''Fixes #1234'', ''Issues #123, #456''
-  - **Sign-off**
+  - **Sign-off** if the commit's author is not a MantisBT core developer
-    * If the commit's author is not a MantisBT core developer, the committer must signoff (''git commit -s'')
-Remember to give credit when it's due (''git commit --author='' or at least a reference in the description)
@@ Line 51: / Line 51: @@
   - **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.
   - **What effects does the patch have?** \\ (In addition to the obvious ones, this may include benchmarks, side effects, etc.)
 ==== Summary ====
 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 **no more than 72** characters 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.
@@ Line 68: / Line 69: @@
 Remember to always add a blank line between Summary and Description.
@@ Line 76: / Line 78: @@
   * ''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.
+=== Configuring editor for word wrap ===
+  * **vi/vim** <code>$ git config --global core.editor "vi -c ':set textwidth=72'"</code> and use the ''gq'' command to reflow the text, e.g. ''gqG'' from current line to end of file
 ==== Description ====
-The commit's Description should be as long as necessary, and must provide
+=== Contents ===
-  * background on change covered by the commit (i.e. //why//).
+The commit's Description should be as long as necessary, and in terms of contents, must
-  * Bugtracker reference (Formatted for use by the Source Integration plugin)
+  * 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 <code>Issue #1234</code>
       * ''Fix[ed|es]|Resolve[d|s] //IssueList//'' -- reference and automatically resolve the listed issue(s), e.g. <code>Fixes #1234, #5678</code>
       * //IssueList//: ''#<issue1>[, #<issue2>...]''
-  * Other useful reference (e.g. CVE ID, link to website...)
+  * add any other useful **references** (e.g. CVE ID, link to website, SHA ID of related commit...).
-  * Credit to the author
+  * give **credit** to the original author. \\ Use ''git commit --author='', or at least name the person in the text.
-  * Signoff by the committer if different from author
+  * be **signed off** by the committer if different from author (see [[git_commit_messages#sign-off|below]])
-Make sure that another person can understand what you wrote, and that //you// would also if going back to it 6 months down the line.
+=== Formatting ===
   * Separate paragraphs with 2 newlines
@@ Line 99: / Line 114: @@
 - bullet 3
 </code>
+=== Sign-off ===
+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.
+===== Examples =====
+Based on model message in Tim Pope's blog post (see [[git_commit_messages#references|references]]).
+<code>
+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>
+</code>
 ===== References =====
@@ Line 107: / Line 163: @@
   * [[https://wiki.gnome.org/Git/CommitMessages|gnome.org's guidelines]]
   * [[https://wiki.openstack.org/wiki/GitCommitMessage|OpenStack's GIT Commit Good Practice]]
+  * [[http://who-t.blogspot.de/2009/12/on-commit-messages.html|Who-T blog on commit messages]]
+  * [[http://chris.beams.io/posts/git-commit/|How to Write a Git Commit Message?]]
+===== To do =====
+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/