<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="content-type" content="text/html;
charset=ISO-8859-1">
</head>
<body bgcolor="#ffffff" text="#000000">
Aloha!<br>
<br>
We probably all agree that it's a good idea to refer to any
pre-existing issue tracker issue IDs a changeset relates to in the
commit message. (If you don't, please let me know me why.) However
we haven't formalized <i>how</i> we refer to them. I think we <i>should</i>
formalize that, so that searching for all changesets relating to a
given issue becomes easier: If some of use use "#123", some "bug
123", others "Bug123" and yet others use "issue no. 123" or
<a class="moz-txt-link-rfc2396E" href="http://redmine.kokuaviewer.org/issues/123">"http://redmine.kokuaviewer.org/issues/123"</a> one would have to search
for all these combinations to find all related changesets.<br>
<br>
There are also some other aspects of commit messages that could
benefit from some uniformity and rules.<br>
<br>
Therefore I'd like to suggest the following policy:<br>
<br>
(If this becomes an actual policy, rules would be mandatory to
follow while recommendations would be mere suggestions on what to do
when unsure.)<br>
<br>
<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>
<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>
<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>
<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>
<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>
<ul>
<li>Example: <tt>KOKUA-123</tt></li>
</ul>
<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>
<ul>
<li><b>Recommendation</b>: Anywhere on that line is fine, but
prefer somewhere near its beginning.</li>
<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>
<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>
<li><b>Recommendation</b>: To fulfill rule 7, describe in prose
what the specific changeset changes and (maybe on further lines)
why. 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.</li>
</ol>
<h2>Rationale<br>
</h2>
Message is already rather long, so I'll follow up with the rationale
for the suggested rules and recommendations above in a separate
message.<br>
<br>
<h2>Food for thought<br>
</h2>
Do we want to require at least one referred-to issue for each
changeset, rather then only references to pre-existing issues? (This
would change rule 2 and would make recommendation 3 superfluous.
<h2>Disclaimer</h2>
<h3>This is not a policy, yet.</h3>
It's just a <i>suggestion</i> for one, as an input for discussion.
Feedback is welcome. Don't want such a policy? Want more/less/other
rules and recommendations? Think my English is awful and the above
needs to be re-formulated? Please say so! If the discussion (by
consensus of the team members) results in a policy, we shall
document that e.g. on the wiki.<br>
<h3>I don't think you're all dumb.</h3>
Some of the above rules and recommendations might be considered
common sense or best practice to some of you that you are already
following and seemingly always have been. I don't want to suggest we
start micro-managing each other, but I think writing down reasonable
policies can be of some merit in heterogeneous communities. Not
everyone of us (or of the potential future contributors and team
members) might be an experienced software developer.<br>
<h3>I don't think you're doing it all wrong.</h3>
If your past or current practice doesn't follow the suggested policy
above, don't worry: I won't blame you, nor will anyone else (I
hope). If we ever agree on a policy, it would off course only apply
to new changesets from then on, not retroactively.<br>
<br>
<br>
That's it for now, I guess. Will follow up with the rationale for
the specific rules and recommendations I suggested, but feel free to
dissect them meanwhile.<br>
<br>
Cheers,<br>
Borun<br>
</body>
</html>