#pragma section-numbers 2
= Writing Good Changeset Comments =
<<TableOfContents>>

Many Mercurial tools use the first line of a [[ChangeSet|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.

== 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.

== 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 &rarr; poor readability
 * Loads of uninformative detail

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

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