[Koha-devel] Commit messages

[Jared Camins-Esakov]

A gentle reminder: if there is information needed for testing a patch, it
should be in your commit message, not just in comments on the bug. If -- in
the course of looking at a patch for pushing to Master -- I follow the test
instructions in a commit message and the patch does not work, or if I can't
quickly divine what the patch is about, I will ask for clarification and
move on. If I don't understand, I have no reason to think that I will start
to understand after spending more time on the issue, and any time I spend
not understanding one patch is time during which no other patch is getting
reviewed.

So, what should be in a commit message to avoid a note from the RM
requesting that you summarize something you already said? Every commit
message should have the following:
1) A subject that includes the bug number at the very beginning of the
line. Something like: "Bug XXXX: enable frobbing the whatsit"
2) A description of what problem the bug addresses, or what feature it
adds. If it's a very simple patch, this might be covered by the subject
line, but probably not. Often you can get this by copying the description
of the bug out of Bugzilla and into your commit message.
3) A detailed test plan. When I say "detailed," I mean that it should
include enough detail that it could be followed by someone familiar with
Koha who does not use whatever section of the code you are editing. A test
plan with forty steps may seem daunting, but it really isn't. It's
considerate. Ideally, the test plan should cover how to confirm the bug
*and* how to confirm that the patch fixed the problem, if the two
procedures are not entirely identical (for example, if your patch involves
Zebra configuration changes, note which files need to be updated; I favor a
tl;dr section which includes information of this sort).
4) I'd also love to see a list or a summary of tests performed by the
person who tested and/or QAed the patch.

Finally, this is not grounds for an irate message from your irascible RM,
but worth a reminder while we are on the subject of commit messages:
ideally we are shooting for a subject which is 50 characters or fewer, and
the body of commit messages should be wrapped at 72 characters. See
http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html for
more on this subject.

In the last month I have pushed 187 patches (some merge commits, of course,
but most not), and we still have a huge backlog on Bugzilla, with little
prospect of the flood slowing (this is a good thing!). Let's work together
so that we can get the backlog down and keep it that way.

Regards,
Jared

P.S. Although I write this from my position as RM, it is worth noting that
these recommendations will help at every stage of the process. Your patches
will get signed off and QAed faster if there's a good test plan, and if
there's a problem with one of your patches people are more likely to try
testing the revised patch if they know that they're not going to have to
flail about trying to figure out how to test it.

-- 
Jared Camins-Esakov
Bibliographer, C & P Bibliography Services, LLC
(phone) +1 (917) 727-3445
(e-mail) jcamins at cpbibliography.com
(web) http://www.cpbibliography.com/
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.koha-community.org/pipermail/koha-devel/attachments/20121128/2c74091b/attachment.html>