mantisbt:git_commit_messages
Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revision | ||
mantisbt:git_commit_messages [2014/05/27 08:14] – Add git commit --author dregad | mantisbt:git_commit_messages [2018/02/06 08:35] (current) – [Checklist] Bug reference examples dregad | ||
---|---|---|---|
Line 1: | Line 1: | ||
- | ====== Git Commit | + | ====== Git Commit |
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:// | + | * Optional, but most commits should reference an issue in the [[http:// |
- | - **Sign-off** | + | - **Sign-off** |
- | * If the commit' | + | |
Line 50: | 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 67: | 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 75: | Line 78: | ||
* '' | * '' | ||
* '' | * '' | ||
+ | |||
+ | === Configuring editor for word wrap === | ||
+ | |||
+ | * **vi/vim** < | ||
+ | |||
==== Description ==== | ==== Description ==== | ||
+ | |||
+ | === Contents === | ||
The commit' | The commit' | ||
Line 93: | Line 103: | ||
* give **credit** to the original author. \\ Use '' | * give **credit** to the original author. \\ Use '' | ||
- | * be **signed off** by the committer if different from author | + | * be **signed off** by the committer if different from author |
- | With regards to formatting | + | === Formatting === |
* Separate paragraphs with 2 newlines | * Separate paragraphs with 2 newlines | ||
Line 104: | Line 114: | ||
- bullet 3 | - bullet 3 | ||
</ | </ | ||
+ | |||
+ | === 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 '' | ||
+ | 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# | ||
+ | |||
+ | < | ||
+ | Capitalized, | ||
+ | |||
+ | 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' | ||
+ | single line | ||
+ | |||
+ | Fixes #5678 (commit will be linked to the issue, which will be marked as | ||
+ | resolved when pushing the commit). | ||
+ | |||
+ | Signed-off-by: | ||
+ | </ | ||
+ | |||
===== References ===== | ===== References ===== | ||
Line 113: | Line 164: | ||
* [[https:// | * [[https:// | ||
* [[http:// | * [[http:// | ||
+ | * [[http:// | ||
+ | |||
+ | ===== To do ===== | ||
+ | |||
+ | Grangeway suggested to implement a commit hook to perform validation on commit message, e.g. | ||
+ | http:// | ||
mantisbt/git_commit_messages.txt · Last modified: 2018/02/06 08:35 by dregad