User Tools
- Logged in as: anonymous (anonymous)
- Log Out
mantisbt:git_commit_messages
Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
mantisbt:git_commit_messages [2014/05/27 07:46] dregad Source integration info moving to Description section |
mantisbt:git_commit_messages [2018/02/06 08:35] dregad [Checklist] Bug reference examples |
||
|---|---|---|---|
| Line 1: | Line 1: | ||
| - | ====== Git Commit Message ====== | + | ====== Git Commit Messages ====== |
| 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 9: | Line 12: | ||
| ===== Checklist ===== | ===== Checklist ===== | ||
| - | See below for further details | + | See [[git_commit_messages#details_and_explanations|Details and explanations section below]] for further information. |
| - **Summary** | - **Summary** | ||
| Line 19: | 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** | + | - **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 40: | Line 40: | ||
| * //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. | * //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). | * //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). | ||
| + | |||
| + | |||
| ===== Details and Explanations ===== | ===== Details and Explanations ===== | ||
| + | |||
| + | A good commit message should basically answer three questions about a patch: | ||
| + | |||
| + | - **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. | ||
| + | - **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.) | ||
| Line 48: | Line 56: | ||
| 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 61: | 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 68: | 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 ==== | ||
| + | |||
| + | === Contents === | ||
| + | |||
| + | 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 <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>...]'' | ||
| + | * 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 [[git_commit_messages#sign-off|below]]) | ||
| + | |||
| + | === Formatting === | ||
| + | |||
| + | * 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 <code> | ||
| + | - bullet 1 | ||
| + | - bullet 2 | ||
| + | some additional text | ||
| + | - 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> | ||
| Line 77: | Line 163: | ||
| * [[https://wiki.gnome.org/Git/CommitMessages|gnome.org's guidelines]] | * [[https://wiki.gnome.org/Git/CommitMessages|gnome.org's guidelines]] | ||
| * [[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://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.txt · Last modified: 2018/02/06 08:35 by dregad
