On Tue, 14 Sep 2010, Dominik Riebeling wrote:

(I changed subject since I try to change the direction of the discussion a
bit here.)

> I don't know if it's just me but at least *I* would really appreciate
> descriptive commit messages since it allows one to more easily follow
> development.

We've been discussing commit "templates" and how to do this before, so I've
given this some thoughts again during this thread and I suggest we start using
a simple but slightly defined system that's similar to what the git people do:

--- start ---
[area]: [short oneline description]

[longish description wrapped at 72 columns that explain why and possibly how
the change is done]
--- end ---

I would also encourge the use a few "magic words" in the long description for
easier reference:

Reported by: [reporter]
Bug: [URL/reference to the bug being fixed/addressed]
Written by: [author] (due to lack of git's --author)

The rationale for the magic words is of course to allow easier extraction
afterwards. Like when you want to figure out who's done a lot of patches, or
which bugs that were fixed within a given interval etc. We can of course
extend them over time, or just not use the ones that we don't find use for.

Example commit message:
---- start ----
backlight e200v1: toggle the correct GPIO

When the moon goes out of phase, it turns out that the memory
map gets reversed and we take a random entrophy to make it right
again.

Reported by: Buggy the Bugreporter
Bug: http://www.rockbox.org/tracker/9763
Written by: Hacker John Doe
--- end ---

The most simple commit message in this system uses only the first short
description and nothing else.

-- 
  / daniel.haxx.se