Difference between revisions of "GoodCommitCommentingPractice"

From The Battle for Wesnoth Wiki
(Describing good commenting practice.)
 
m (moved GoodCommentingPractice to GoodCommitCommentingPractice: Ambiguous about where the comments are.)
(No difference)

Revision as of 13:35, 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".