[gentoo-dev] Proper commit messages

[Ciaran McCreesh]

Well, you'd think that doing main tree CVS commit messages would be

something that everyone could do properly without being told, but sadly

this doesn't seem to be the case. Soooo...



Believe it or not, commit messages are not just something that you type

in to keep a computer happy. These messages are also read by QA and arch

people.



If you're not a QA or arch person, and you don't consider spending a few

moments to make life easier for those people to be sufficient reason,

you might want to consider that repeated ``cvs diff`` runs will hit the

CVS server far more than one ``cvs log``.



If you're the sort that writes good ChangeLog messages anyway, there's

nothing wrong with reusing them as the commit message. If you have a

really really good reason for not using a ChangeLog message, or if you

haven't yet written a shell alias for reusing ChangeLog messages for

commits, you still need to come up with something for the commit

message.



Your commit message should explain what specifically you changed and, if

relevant, why. You don't need to write an essay or even a complete

sentence (ChangeLog messages, however, *are* required to be in 'proper'

English), so long as it is easily understandable and (preferably)

greppable. Examples, all of which are based upon real messages:



BAD:  Changed keywords

GOOD: Added ~x86 keyword



BAD:  Stable

GOOD: Stable on x86, sparc, mips



BAD:  Fix stuff

GOOD: Fix USE=foo logic error



BAD:  .

GOOD: Purge old ebuilds



BAD:  Vérifiez que le frozbinateur n'est pas cassé.

GOOD: Added a check for broken frozbinator.



BAD:  Who the fuck reads these anyway?

GOOD: Version bump.



Whilst I'm at it, I might as well comment on some things that are useful

in ChangeLogs that don't always get done properly:



* Any relevant bug numbers, formatted like "bug #20600". The # is

  important, it's used by various things (eg packages.g.o) that

  automagically add links to text.



* What that patch you're adding actually does.



* The archs you're working with when keywording. "Marked stable" is a

  nuisance for arch people, even if there was only one keyword in the

  ebuild at the time. "Stable on all archs" isn't generally any better

  (and should you really be stabling on all archs?) -- do you mean

  "all", or "all the ones that are currently keyworded"? A list like

  "x86 sparc mips" is much more useful.



This rant was not inspired by someone committing a bunch of things with

one character (and a punctuation character at that) commit messages

despite repeatedly having been asked not to. Honest.



-- 

Ciaran McCreesh : Gentoo Developer (Vim, Shell tools, Fluxbox, Cron)

Mail            : ciaranm at gentoo.org

Web             : http://dev.gentoo.org/~ciaranm