Differences between revisions 7 and 15 (spanning 8 versions)
Revision 7 as of 2008-01-05 14:25:20
Size: 1344
Editor: abuehl
Comment:
Revision 15 as of 2013-01-24 04:46:17
Size: 1699
Editor: rcl
Comment: add section numbering
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
== Writing good changeset comments == #pragma section-numbers 2
= Writing Good Changeset Comments =
<<TableOfContents>>
Line 3: Line 5:
Many Mercurial tools use the first line of a ChangeSet comment as a short-form description of the changeset. Many Mercurial tools use the first line of a [[ChangeSet|changeset]] comment as a short-form description of the changeset.
Line 11: Line 13:
== Good Example ==
Line 27: Line 30:
== Bad Example ==
Line 40: Line 44:
 * No paragraph breaks -> poor readability  * No paragraph breaks &rarr; poor readability
Line 42: Line 46:

== See also ==
 * For comments on contributed patches to Mercurial, see [[ContributingChanges#Patch_descriptions|Patch descriptions]]
----
CategoryHowTo

[[ThaiChangeSetComments|ภาษาไทย]], [[JapaneseChangeSetComments|日本語]]

Writing Good Changeset Comments

Many Mercurial tools use the first line of a changeset comment as a short-form description of the changeset.

You should thus treat the first line like the subject line of an email message. It should:

  • stand alone,
  • be less than 65 characters long, and
  • give a quick idea of the content of the changeset.

1. Good Example

Here is an example of a good changeset comment:

 First stab at the veeblefrotzer subsystem

 Implemented using the McWhirly/O'Blivet technique.

 Displays correctly on the twelfth of every month,
 but doesn't yet work during the other 27-30 days.

This has a few things going for it:

  • The first line succinctly describes the change.
  • The entire comment is short and informative.
  • It mentions known shortcomings.

2. Bad Example

Here's a bad example:

 Implemented the veeblefrotzer subsystem, which uses the
 McWhirly/O'Blivet scheme for envolvolution of the subducted
 whingnangle.  See McWhirly, O'Blivet, "Acta Exsanguinata", vol. III,
 chap. 19 for a concise description of the technique, unless you can't
 find the chapter because someone has razored it out and papered it to
 the walls of their cube.

What's so bad about it?

  • First line doesn't stand alone
  • No paragraph breaks → poor readability

  • Loads of uninformative detail

3. See also


CategoryHowTo

ภาษาไทย, 日本語

ChangeSetComments (last edited 2013-01-24 04:46:17 by rcl)