[GRASS-dev] Submitting rules: Commit messages

[Vaclav Petras]

On Sun, Jun 29, 2014 at 8:05 AM, Glynn Clements <glynn at gclements.plus.com>
wrote:

>
> 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.
>
> If you refer to file names, I hope I wrote there that they should not be
included. If you refer to the prefix with library/module/component name, I
are right that it is a duplication but I think that it is also summary of
the file list.


> > 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.
>
> I cannot agree, commit messages are here to learn about the commit and
perhaps even something in general. If I'm reading some code and I don't
understand why this is there (because there is no explicit comment) I can
see blame/annotate with a commit message saying why this was added/changed.

However, if there is just ticket number I have to go to the ticket, read it
and think how it relates to the diff which might be tough (remember some of
the long multi-topic tickets). If there is a "fix bug introduced in r1234"
I have no idea which bug. If some missing library is added to Makefile I
can perhaps guess a build issue but with some additional call of some
function or addition of parameter I have no clue, was it flickering in NVIZ
or compilation error?

I acknowledge that this is really opinion based and there is a lot of
different opinions but I think that we should not ask people to study
tickets to understand why is our commit useful. The issue might be
sometimes even more apparent with references to older commits when we ask
other people to read the diff, and maybe even switch to that revision to
find what was the bug we are referring to.

Vaclav

--
> Glynn Clements <glynn at gclements.plus.com>
> _______________________________________________
> grass-dev mailing list
> grass-dev at lists.osgeo.org
> http://lists.osgeo.org/mailman/listinfo/grass-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/grass-dev/attachments/20140629/5370e8f0/attachment.html>