Size: 1360
Comment:
|
Size: 1608
Comment:
|
Deletions are marked like this. | Additions are marked like this. |
Line 1: | Line 1: |
<<Include(A:style)>> comments for contributing to mercurial see [[ContributingChanges#Patch_descriptions|Patch descriptions]] |
|
Line 3: | Line 7: |
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 9: | Line 13: |
* give a quick idea of the content of the ChangeSet. | * give a quick idea of the content of the changeset. |
Line 11: | Line 15: |
Here is an example of a good ChangeSet comment: | Here is an example of a good changeset comment: |
Line 16: | Line 20: |
Implemented using the McWhirly/O'Blivet technique. | Implemented using the McWhirly/O'Blivet technique. |
Line 18: | Line 22: |
Displays correctly on the twelfth of every month, but doesn't yet work during the other 27-30 days. |
Displays correctly on the twelfth of every month, but doesn't yet work during the other 27-30 days. |
Line 32: | Line 35: |
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. |
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. |
Line 42: | Line 44: |
* No paragraph breaks -> poor readability | * No paragraph breaks → poor readability |
Line 44: | Line 46: |
---- CategoryHowTo [[ThaiChangeSetComments|ภาษาไทย]], [[JapaneseChangeSetComments|日本語]] |
|
comments for contributing to mercurial see Patch descriptions
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.
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.
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