[GRASS-dev] Submitting rules: Commit messages

[Glynn Clements]

Vaclav Petras wrote:

> please read, comment and follow:
> 
> http://trac.osgeo.org/grass/wiki/Submitting/General#Commitmessages

Personally, I don't favour duplicating information which is stored
elsewhere (e.g. which files are affected).

The auto-generated emails list the affected files, as does the Trac
"Timeline" page. In the source browser, revision logs are generated
for specific files and directories.

> fix bug introduced in r60216
> (missing information how the bug was fixed and which bug it was)

If a commit has a bug, and a subsequent commit fixes it shortly
afterwards, before any ticket has been opened or before anyone else
has commented on it or even noticed it, there's really no need to
include the details (anyone wanting them can look at the diff itself).

Commit summaries should, IMHO, be sufficient to identify a specific
commit given that you already know roughly what you're looking for. 
E.g. if you know that something broke in particular way in a given
interval, the summaries should help to identify which commits are
"likely suspects" worthy of closer examination.

If you know that something broke in r1234, then "fixed bug in r1234"
should be all you need to identify the commit you're looking for.

If you're familiar with the code, its structure and its history, you
don't need anything more. If you aren't, you're probably going to need
to read the actual diff, and a verbose summary won't change that.

-- 
Glynn Clements <glynn at gclements.plus.com>