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.2. [Testing](#Testing)<br />
|
||||
4.3. [Code Documentation and Commenting](#CodeDocumentation)<br />
|
||||
4.4. [Model Git Commit Messages](#ModelGitCommitMessages)<br />
|
||||
5. [Code Approval Process](#CodeApproval)<br />
|
||||
5.1 [Code Review](#CodeReview)<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
|
||||
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" />
|
||||
### 5. Code Approval Process
|
||||
|
||||
|
|
Loading…
Reference in a new issue