docs: Add info describing model commit messages.
This commit is contained in:
parent
2dc8687728
commit
88b15e74f0
1 changed files with 47 additions and 0 deletions
|
@ -6,6 +6,7 @@
|
||||||
4.1. [Share Early, Share Often](#ShareEarly)<br />
|
4.1. [Share Early, Share Often](#ShareEarly)<br />
|
||||||
4.2. [Testing](#Testing)<br />
|
4.2. [Testing](#Testing)<br />
|
||||||
4.3. [Code Documentation and Commenting](#CodeDocumentation)<br />
|
4.3. [Code Documentation and Commenting](#CodeDocumentation)<br />
|
||||||
|
4.4. [Model Git Commit Messages](#ModelGitCommitMessages)<br />
|
||||||
5. [Code Approval Process](#CodeApproval)<br />
|
5. [Code Approval Process](#CodeApproval)<br />
|
||||||
5.1 [Code Review](#CodeReview)<br />
|
5.1 [Code Review](#CodeReview)<br />
|
||||||
5.2 [Rework Code (if needed)](#CodeRework)<br />
|
5.2 [Rework Code (if needed)](#CodeRework)<br />
|
||||||
|
@ -194,6 +195,52 @@ if amt < 5460 {
|
||||||
but it was left as a magic number to show how much of a difference a good
|
but it was left as a magic number to show how much of a difference a good
|
||||||
comment can make.
|
comment can make.
|
||||||
|
|
||||||
|
<a name="ModelGitCommitMessages" />
|
||||||
|
### 4.4 Code Documentation and Commenting
|
||||||
|
|
||||||
|
This project prefers to keep a clean commit history with well-formed commit
|
||||||
|
messages. This section illustrates a model commit message and provides a bit
|
||||||
|
of background for it. This content was originally created by Tim Pope and made
|
||||||
|
available on his website, however that website is no longer active, so it is
|
||||||
|
being provided here.
|
||||||
|
|
||||||
|
Here’s a model Git commit message:
|
||||||
|
|
||||||
|
```
|
||||||
|
Short (50 chars or less) summary of changes
|
||||||
|
|
||||||
|
More detailed explanatory text, if necessary. Wrap it to about 72
|
||||||
|
characters or so. 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 present tense: "Fix bug" and not "Fixed
|
||||||
|
bug." This convention matches up with commit messages generated by
|
||||||
|
commands like git merge and git revert.
|
||||||
|
|
||||||
|
Further paragraphs come after blank lines.
|
||||||
|
|
||||||
|
- Bullet points are okay, too
|
||||||
|
- Typically a hyphen or asterisk is used for the bullet, preceded by a
|
||||||
|
single space, with blank lines in between, but conventions vary here
|
||||||
|
- Use a hanging indent
|
||||||
|
```
|
||||||
|
|
||||||
|
Here are some of the reasons why wrapping your commit messages to 72 columns is
|
||||||
|
a good thing.
|
||||||
|
|
||||||
|
- git log doesn’t do any special special wrapping of the commit messages. With
|
||||||
|
the default pager of less -S, this means your paragraphs 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 converts a series of commits to a series of emails,
|
||||||
|
using the messages 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.
|
||||||
|
|
||||||
<a name="CodeApproval" />
|
<a name="CodeApproval" />
|
||||||
### 5. Code Approval Process
|
### 5. Code Approval Process
|
||||||
|
|
||||||
|
|
Loading…
Reference in a new issue