User Tools

  • Logged in as: anonymous (anonymous)
  • Log Out

Site Tools


mantisbt:git_commit_messages

Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
mantisbt:git_commit_messages [2014/05/27 08:22]
dregad
mantisbt:git_commit_messages [2018/02/06 08:35] (current)
dregad [Checklist] Bug reference examples
Line 3: Line 3:
 This document provides guidelines on how to write a well-formed commit message This document provides guidelines on how to write a well-formed commit message
 when developing for MantisBT. when developing for MantisBT.
 +
 +
  
  
Line 20: Line 22:
     * Always add a **blank line** between summary and description     * Always add a **blank line** between summary and description
     * Wrap lines at **72 characters**     * 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**   - **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** if the commit'​s author is not a MantisBT core developer   - **Sign-off** if the commit'​s author is not a MantisBT core developer
  
Line 49: 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.   - **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.)   - **What effects does the patch have?** \\ (In addition to the obvious ones, this may include benchmarks, side effects, etc.)
 +
  
 ==== Summary ==== ==== Summary ====
  
 The Summary line is used all over Git, oftentimes in truncated form if it is too long. 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. 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 66: Line 69:
  
 Remember to always add a blank line between Summary and Description. Remember to always add a blank line between Summary and Description.
 +
  
  
Line 74: 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 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.   * ''​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 ==== ==== Description ====
 +
 +=== Contents ===
  
 The commit'​s Description should be as long as necessary, and in terms of contents, must  The commit'​s Description should be as long as necessary, and in terms of contents, must 
Line 92: Line 103:
   * give **credit** to the original author. \\ Use ''​git commit --author='',​ or at least name the person in the text.   * 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 ​\\ Use ''​git commit ​-s''​+  * be **signed off** by the committer if different from author ​(see [[git_commit_messages#​sign-off|below]])
  
-With regards to formatting+=== Formatting ===
  
   * Separate paragraphs with 2 newlines   * Separate paragraphs with 2 newlines
Line 103: Line 114:
 - bullet 3 - bullet 3
 </​code>​ </​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 ===== ===== References =====
Line 112: Line 164:
   * [[https://​wiki.openstack.org/​wiki/​GitCommitMessage|OpenStack'​s GIT Commit Good Practice]]   * [[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://​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/​
  
mantisbt/git_commit_messages.1401193320.txt.gz · Last modified: 2014/05/27 08:22 (external edit)