Difference between revisions of "GoodCommitCommentingPractice"
m (moved GoodCommentingPractice to GoodCommitCommentingPractice: Ambiguous about where the comments are.) |
(Added bullet point 5.) |
||
| Line 12: | Line 12: | ||
5. If you are reverting a commit, git will generate a line referring to it. Please replace the git hex ID with something more human-friendly, like "my last commit", or "Joe-Bob's change to Xena's chakram graphics". | 5. If you are reverting a commit, git will generate a line referring to it. Please replace the git hex ID with something more human-friendly, like "my last commit", or "Joe-Bob's change to Xena's chakram graphics". | ||
| + | |||
| + | 6. Use the project's standard abbreviations for campaigns, like HttT for Heir to the Throne. To refer to a numbered scenario, you can do this: HttT::5 points at scenario 5. | ||
Revision as of 14:38, 25 February 2013
Wesnoth is in the process of moving to the git version-control system. The move may be complete by the time you read this.
In order to make your commit comments play nice with tools such as git log and gitk, please follow these formatting guidelines (which are good practice even off git):
1. Every comment should begin with a self-contained summary line no more than 72 characters long. This is the first (and often the only) line someone using browsing tools will see.
2. If your comment needs more than a summary line, separate it from the rest (the running text of the comment) with a blank line.
3. Lines in running text should also be no more than 72 characters long. Use blank lines to separate paragraphs and list items.
4. If you are merging, git may generate text for your comment listing file conflicts. Edit this out; it ceases to be interesting after the conflict has been resolved.
5. If you are reverting a commit, git will generate a line referring to it. Please replace the git hex ID with something more human-friendly, like "my last commit", or "Joe-Bob's change to Xena's chakram graphics".
6. Use the project's standard abbreviations for campaigns, like HttT for Heir to the Throne. To refer to a numbered scenario, you can do this: HttT::5 points at scenario 5.