Difference between revisions of "User:8680/GitGoodPractice"
From The Battle for Wesnoth Wiki
(→Commit messages) |
|||
| Line 6: | Line 6: | ||
== Commit messages == | == Commit messages == | ||
* A commit message consists of a summary line and a message body, which must be separated with a blank line. | * A commit message consists of a summary line and a message body, which must be separated with a blank line. | ||
| − | |||
| − | |||
* The summary line should <strong>summarize</strong> the message body in such a way as to be as useful as possible for developers reviewing the commit history in the future. | * The summary line should <strong>summarize</strong> the message body in such a way as to be as useful as possible for developers reviewing the commit history in the future. | ||
| − | ** The summary line should be written in “imperative present tense”. | + | ** The summary line should be written in “imperative present tense” — e.g., “Fix issue X”, not “Fixes issue X”, “Fixed issue X”, or “Fixing issue X”. |
| − | ** The summary line should be a sentence, | + | ** The summary line should be a sentence, except without a full-stop character at the end. |
| − | ** The summary line should be limited to 50 characters or less. | + | *** The summary line should be in sentence case — e.g., “Fix Latin translation”, not “Fix Latin Translation” or “fix latin translation”. |
| + | ** The summary line should be limited to 50 characters (or, rather, 50 <em>columns</em>; some characters can occupy multiple columns) or less. | ||
*** shadowm professed to prefer an 80-character limit, but later clarified that that preference is not to be taken as policy. | *** shadowm professed to prefer an 80-character limit, but later clarified that that preference is not to be taken as policy. | ||
| + | * The message body should <strong>describe and explain</strong> the changes made in the commit, and the <strong>rationale</strong> behind those changes, <strong>as fully as possible</strong>. | ||
| + | ** The message body should be hard-wrapped to <strong>72 characters</strong> (or columns). | ||
| + | ** The message body should be written in imperative present tense like the summary line, <em>if feasible</em>. Longer (better!) message bodies may be awkward or infeasible to write in imperative present tense; in such cases, it’s okay to write the message body in non-imperative present tense — e.g., “This commit fixes issue X, by making changes that I will now describe and explain in extensive detail.”. | ||
== Pull requests == | == Pull requests == | ||
* A pull request should always request the pull of a <strong>topic branch, never a long-running branch</strong> (like a ‘master’ branch). | * A pull request should always request the pull of a <strong>topic branch, never a long-running branch</strong> (like a ‘master’ branch). | ||
* A pull request should be <strong>self-contained</strong>, like a commit should be. | * A pull request should be <strong>self-contained</strong>, like a commit should be. | ||
Revision as of 02:08, 14 March 2014
Commits
- A commit should be, to quote shadowm, “sufficiently self-contained that it can be reverted […] without leaving any related changes behind”.
- A commit to a long-running (or otherwise non-topic) branch should work on its own, without requiring subsequent commits.
- It’s fine for a commit to not work (or only partially work) if it’s a commit to a temporary topic branch, which is to be merged into (not rebased onto) another branch when the commit series achieves full functionality.
- A commit to a long-running (or otherwise non-topic) branch should work on its own, without requiring subsequent commits.
Commit messages
- A commit message consists of a summary line and a message body, which must be separated with a blank line.
- The summary line should summarize the message body in such a way as to be as useful as possible for developers reviewing the commit history in the future.
- The summary line should be written in “imperative present tense” — e.g., “Fix issue X”, not “Fixes issue X”, “Fixed issue X”, or “Fixing issue X”.
- The summary line should be a sentence, except without a full-stop character at the end.
- The summary line should be in sentence case — e.g., “Fix Latin translation”, not “Fix Latin Translation” or “fix latin translation”.
- The summary line should be limited to 50 characters (or, rather, 50 columns; some characters can occupy multiple columns) or less.
- shadowm professed to prefer an 80-character limit, but later clarified that that preference is not to be taken as policy.
- The message body should describe and explain the changes made in the commit, and the rationale behind those changes, as fully as possible.
- The message body should be hard-wrapped to 72 characters (or columns).
- The message body should be written in imperative present tense like the summary line, if feasible. Longer (better!) message bodies may be awkward or infeasible to write in imperative present tense; in such cases, it’s okay to write the message body in non-imperative present tense — e.g., “This commit fixes issue X, by making changes that I will now describe and explain in extensive detail.”.
Pull requests
- A pull request should always request the pull of a topic branch, never a long-running branch (like a ‘master’ branch).
- A pull request should be self-contained, like a commit should be.