<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta content="text/html; charset=ISO-8859-1"
http-equiv="Content-Type">
</head>
<body bgcolor="#ffffff" text="#000000">
As promised, here my<br>
<h2>Rationale for the suggested policy on commit messages</h2>
<h3>Why a written policy?</h3>
Up to now, most of what we've done didn't follow any written-down
rules except for the rather general <a
href="http://wiki.kokuaviewer.org/wiki/Official:Imprudence_Manifesto">Imprudence
Manifesto</a>. This doesn't mean we didn't have any rituals, fixed
processes and best practices, but they were passed on interactively
(I'd say 'orally' but most of our communication is text-chat based)
and often probably inconsistently. Not having been particularly
active, I myself probably don't even know most of them, yet. Having
a small team lead by a benevolent dictator, this wasn't much of a
problem. If there were doubts on how to do something, we could
always just ask Jacek who'd decide on a case-by-case basis.<br>
<br>
Now that <a
href="http://blog.kokuaviewer.org/2011/08/16/help-wanted-project-organizer-developers/">we
want to grow both our team and our base of contributors</a>, while
at the same time facing a <a
href="http://blog.kokuaviewer.org/2011/08/02/moving-on/">change of
leadership</a>, it's probably worth to find consensus on some
stuff and then write it down, so we can later easily refer to it and
direct others to this material as a kind of process documentation.
While a large set of rules and policies might be daunting to new
participants, it can also help them get going: It can be rather
frustrating if you do something, then hear there's some unwritten
rule to do it differently, then do it again differently, then hear
of another rule you're violating etc. until your contribution
finally meets the quality standards a project might set. It's much
easier if you have to go through this iteration only once and then
are able to check your change yourself against a full set of
requirements that you've been referred to.<br>
<h3>Why these specific rules?</h3>
<br>
On 08/23/2011 11:47 PM, Borun (a.k.a. Boroondas Gupte) wrote:<br>
<blockquote cite="mid:4E54200D.8030902@kokuaviewer.org" type="cite">
<ol>
<li>The following rules and recommendations only apply to
changesets we, the Kokua contributors and Kokua project
members, originally commit, not changesets we pull or
cherry-pick from other projects' repositories.</li>
</ol>
</blockquote>
<ul>
<li>Pulled changesets are unaltered by definition, so they have
whatever commit message they already had in the original
repository.</li>
<li>When cherry-picking changesets we should not alter them (incl.
the commit message), so that it's easily visible what came from
the cherry-picked changeset and what is our own doing.</li>
<ul>
<li>Exception: Including info about where the changeset was
pulled from (as <tt>hg transplant --log</tt> does) might be
useful.</li>
</ul>
<li>When we can't use a pulled/picked change as-is, we should put
our own changes in separate changesets on top.</li>
</ul>
<br>
<blockquote cite="mid:4E54200D.8030902@kokuaviewer.org" type="cite">
<ol start="2">
<li><b>Rule</b>: A changeset that is <b>intended to (partially)
fix or implement</b> one or several bugs/features/changes
already filed on our issue tracker (redmine.kokuaviewer.org) <b>must</b>
refer to at least one of the corresponding issue ID in its
commit message.</li>
<li><b>Recommendation</b>: A changeset that is <b>loosely
related to</b> one or several bugs/features/changes already
filed on our issue tracker (and not fixing or implementing any
other tracked issues) <b>should</b> refer to at least one of
the corresponding issue ID in its commit message.</li>
</ol>
</blockquote>
So you know where to find more information about a given changeset.<br>
<br>
<blockquote cite="mid:4E54200D.8030902@kokuaviewer.org" type="cite">
<ol start="4">
<li><b>Recommendation</b>: A changeset that fixing, implementing
or relating to <b>several</b> issues <b>should</b> refer to
all of them.</li>
</ol>
</blockquote>
So you can identify all changesets relating to a given issue.<br>
<br>
<blockquote cite="mid:4E54200D.8030902@kokuaviewer.org" type="cite">
<ol start="4">
<ol>
</ol>
<ul>
<li><b>Exception</b>: There is no need to refer to issues
closed as duplicates of other issues, when those other
issues are being referred to already.</li>
</ul>
</ol>
</blockquote>
For duplicates, you'd usually search for issues relating to the
duplicated issue instead, assuming they also relate to the
duplicating issue you're interested in. If there is a clear
subset-superset relation between duplicating and duplicated issue or
if the duplicating one is especially noteworthy, it can of course
still be referred to directly in the commit message.<br>
<br>
<blockquote cite="mid:4E54200D.8030902@kokuaviewer.org" type="cite">
<ol start="5">
<ol>
</ol>
<li><b>Rule</b>: The references of rule 2 (and of recommendation
3 and 4, if any) <b>must</b> be of the format <tt>KOKUA-<i><issue
ID></i></tt>, where <tt><i><issue ID></i></tt>
is the Redmine issue number on your issue tracker without the
leading <tt>'#'</tt>.</li>
<ol>
</ol>
<ul>
<li>Example: <tt>KOKUA-123</tt></li>
</ul>
</ol>
</blockquote>
A fixed format for the references makes searching for all issues
related to a given issue easier. (A single <tt>hg log -k</tt>
call.)<br>
<br>
Armin, who's probably been the most active committer on Kokua so
far, has been using a format like "fix Bug #4711 <Title of the
issue>" himself. So why am I suggesting a different one? I think
having the project name explicitly in the reference has some
advantages:<br>
<ul>
<li>If we pull from other projects which also use an issue tracker
that just uses sequential numbers as issue IDs (maybe Bugzilla,
or also Redmine), this makes it possible to distinguish between
references to their and our issues, which is necessary for
knowing in which issue tracker you'd have to look for an issue,
without knowing which committer is member/contributor of which
project. It'd be very unlikely that their issue #123 is the same
as our #123.<br>
</li>
<ul>
<li>There might also be committers who are contributors of
several projects, so the project name in the reference becomes
the only clue where to look. (Except for the named branch
branch name (sic!), if we continue to use that. Not sure
whether we should, as it 'pollutes' the branch namespace of
everyone pulling from us, too.)<br>
</li>
</ul>
<li>The same goes of course also for others' repositories when
they pull from us.</li>
<li>If others pull our changesets, they'll get them "branded" with
our project name. --> Free advertising that is proportional
to the popularity of our changesets! ;-)<br>
</li>
</ul>
<br>
<blockquote cite="mid:4E54200D.8030902@kokuaviewer.org" type="cite">
<ol start="6">
<ol>
</ol>
<li><b>Rule</b>: The references of rule 2 (and of recommendation
4, if any) in the format of rule 5 <b>must</b> be located on
the first line of the commit message.</li>
</ol>
</blockquote>
While the mercurial (and git) backend treat the whole commit message
as just some unstructured textual data, the frontend treats the
first line specially and interprets it as the "subject line" of the
message: <tt>hg log</tt> (without <tt>-v</tt>) displays just this
line instead of the whole message.<br>
<br>
When skimming over a log, I'd like to see the relevant issue IDs
without having to use <tt>-v</tt> (which would also give me lengthy
change descriptions I might not be interested in).<br>
<br>
<blockquote cite="mid:4E54200D.8030902@kokuaviewer.org" type="cite">
<ol start="6">
<ol>
</ol>
<ul>
<li><b>Recommendation</b>: Anywhere on that line is fine, but
prefer somewhere near its beginning.</li>
</ul>
</ol>
</blockquote>
Near the beginning makes it easier to spot on messages with long
"subject line". (Though, try to keep that line somewhat concise, if
possible.) I don't want to pin the position to exactly the
beginning, so we can still write naturally "Fixed Bug
KOKUA-<something>" or "Implemented KOKUA-123" etc.<br>
<br>
<blockquote cite="mid:4E54200D.8030902@kokuaviewer.org" type="cite">
<ol start="6">
<ul>
<li>Note: <b>Additional</b> references in the same or other
formats on the first line or anywhere else in the commit
message are fine where they make sense. We just require <b>one</b>
reference to each referred-to issue be on the first line and
of the mentioned format.</li>
</ul>
</ol>
</blockquote>
One reference to the issue in the 'standard' format is sufficient
for finding it. As the "KOKUA-<something>" format is a bit
lengthy, it might be convenient to refer just with the #-notation
(or any other easy-to-understand way) to the same issues again in
the same message.<br>
<br>
Example:<br>
"KOKUA-4000, KOKUA-2203: Check for nullpointers in
llFooBar::bazHandler<br>
<br>
This fixes the crashes seen when the handled baz has already been
deleted (Bug #4000) and finally makes our sources pass all sanity
tests of cppcheck (Issue 2203). Yay!"<br>
<br>
<blockquote cite="mid:4E54200D.8030902@kokuaviewer.org" type="cite">
<ol start="7">
<ol>
</ol>
<li><b>Rule</b>: The first line of the commit message <b>must</b>
contain some description of the change besides the ID
references required above.</li>
</ol>
</blockquote>
When skimming over a log, I'd like to be able to (roughly) figure
out what each changeset does, without having to use <tt>-v</tt>, <tt>-p</tt>
or looking up each mentioned issue in the tracker. At least to the
point that allows me to decide which of the issues to examine
further with either<tt> -v</tt>, <tt>-p</tt> or by looking at the
issues.<br>
<br>
<blockquote cite="mid:4E54200D.8030902@kokuaviewer.org" type="cite">
<ol start="8">
<li><b>Recommendation</b>: To fulfill rule 7, describe in prose
what the specific changeset changes and (maybe on further
lines) why. [...]<br>
</li>
</ol>
</blockquote>
Well, that's the purpose of the commit message in general and
especially of its 'subject line'.<br>
<br>
<blockquote cite="mid:4E54200D.8030902@kokuaviewer.org" type="cite">[...
(continued)] If you feel unable to come up with something
appropriate, simply include the "subject" line of one of the
referred issues, maybe prepended by "fixed" or "implemented" as
appropriate.<br>
</blockquote>
This is to make rule 7 less scary to those who dislike writing. :-)<br>
If the issue's subject is formulated as a task (imperative), using
it as the changeset subject as-is should usually work quite well. If
though it's description of unwanted (in case of a bug) or wanted (in
case of a feature request) behavior, prepending "fixed" or
"implemented" respectively allows to tell whether the changeset is
supposed to introduce or remove the described behavior.<br>
<br>
<br>
Again, this all is meant as a base for discussion. Feedback is
welcome.<br>
<br>
Cheers,<br>
Borun<br>
</body>
</html>