Simon Laws wrote:
I find
"Fix TUSCANY-xxx"
Less satisfactory than
TUSCANY-xxx change abc because ...
or
change abc because ...
For two reasons.
1/ I often look at the log of changes for a given file or a group if
files. This shows a list of changes and having to de-reference to the
JIRA is a pain when you are trying to get an overview of the ebb and
flow of changes in a particular area. This is particularly the case
when you are reading down a long list trying to find the particular
change that is contributing to whatever problem you are currently
working on. I think of it like reading the "CHANGES" file we create
for a release as a whole. I find having just JIRA numbers there is
also less that satisfactory.
2/ A JIRA often has many changes associated with it and tying down the
reason for one particular change, even within the context of a single
JIRA, is not always easy
When I fix a JIRA, I usually do a single commit for all the changes.
This will have a single commit comment. It would be much more burdensome
to do multiple commits so that a tailored comment can be used for each
separate change. If a more detailed breakdown of the changes for a
complex fix is needed, I think the best place for this is the JIRA.
We may get to the point where it's a question of taste. It doesn't
seem to me to be a great burden to put a sentence of explanation in at
the point at which a change is committed, the point at which the
change is fresh in the committers mind, to help those of us who find
it useful regardless of whether the committer is going to use it in
the future
In the case described above with many changes to fix a single JIRA,
it would be very difficult to come up with a one-sentence summary
that's more helpful than "Fixed TUSCANY-xxxx". It would be possible
to add a bit more information about the JIRA problem (e.g., "incorrect
WSDL generated"). For more than that, I think the JIRA is the right
place.
Simon
I am not proposing that for 2.x we have a JIRA for ever change. It is
attractive for 1.x though where the changes are becoming more about
maintenance and less about new development.
Simon
