Same here. I prefer to use JIRA to track the details.
Thanks,
Raymond
--------------------------------------------------
From: "Simon Nash" <n...@apache.org>
Sent: Tuesday, June 02, 2009 7:17 AM
To: <dev@tuscany.apache.org>
Subject: Re: Commit comment quality?
ant elder wrote:
On Fri, May 29, 2009 at 5:36 PM, Simon Laws <simonsl...@googlemail.com>
wrote:
I've noticed over the last couple of months that we have, on some
occasions, become a little lax about adding the "why" alongside the
"what" in our commit comments. Particularly problematic when there is
no JIRA to refer to. I'm as much a culprit as anyone else so I'm not
throwing rocks here but it would be useful to me if, as we're
reviewing each others changes, we can call out when we think the
comment isn't sufficient or clear enough so that the justification can
be updated and it becomes a matter of record. I seems that there are
some innovative discussions firing up on 2.x and it would be good to
be able to help people follow the twists and turns as best we can.
Is this a fair observation?
Simon
+1. Commit comments saying why not what with as much detail as is
necessary to help others understand the change remembering that
there's lots of room so more than one sentence is ok if required. Also
several small discrete commits are easier to understand than one
commit which has several different changes. Also try to do formatting
changes separately because it can be real hard to see whats changed if
formatting is mixed with other code changes. And another type i find a
bit irksome is comments that only mention a JIRA number eg "Fix
TUSCANY-xxxx" but not what the JIRA is about so you have to go look it
up yourself.
...ant
I have often used the "Fix TUSCANY-xxx" style of commmit comment,
together with a longer comment in the JIRA explaining the change.
IMO this is better than putting the long explanation in the commit
comment, because it makes it easier for people to find the
explanation later. I don't find it inconvenient to look in a
JIRA to get this information.
For commits without a JIRA, I agree that a longer explanatory
commit comment is desirable.
Simon
