[gentoo-dev] Proper commit messages

[Ciaran McCreesh <ciaranm@gentoo.org>]

[-- Attachment #1: Type: text/plain, Size: 2782 bytes --]

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


[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]