[kokua-dev] Rationale for the suggested policy on commit messages (was: Referring to Redmine issues in commit messages / Suggestion for a policy on commit messages)

[Borun (a.k.a. Boroondas Gupte)]

As promised, here my


    Rationale for the suggested policy on commit messages


      Why a written policy?

Up to now, most of what we've done didn't follow any written-down rules
except for the rather general Imprudence Manifesto
<http://wiki.kokuaviewer.org/wiki/Official:Imprudence_Manifesto>. 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.

Now that we want to grow both our team and our base of contributors
<http://blog.kokuaviewer.org/2011/08/16/help-wanted-project-organizer-developers/>,
while at the same time facing a change of leadership
<http://blog.kokuaviewer.org/2011/08/02/moving-on/>, 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.


      Why these specific rules?


On 08/23/2011 11:47 PM, Borun (a.k.a. Boroondas Gupte) wrote:
>
>    1. 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.
>
    * Pulled changesets are unaltered by definition, so they have
      whatever commit message they already had in the original repository.
    * 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.
          o Exception: Including info about where the changeset was
            pulled from (as hg transplant --log does) might be useful.
    * When we can't use a pulled/picked change as-is, we should put our
      own changes in separate changesets on top.


>    2. *Rule*: A changeset that is *intended to (partially) fix or
>       implement* one or several bugs/features/changes already filed on
>       our issue tracker (redmine.kokuaviewer.org) *must* refer to at
>       least one of the corresponding issue ID in its commit message.
>    3. *Recommendation*:  A changeset that is *loosely related to* one
>       or several bugs/features/changes already filed on our issue
>       tracker (and not fixing or implementing any other tracked
>       issues) *should* refer to at least one of the corresponding
>       issue ID in its commit message.
>
So you know where to find more information about a given changeset.

>    4. *Recommendation*: A changeset that fixing, implementing or
>       relating to *several* issues *should* refer to all of them.
>
So you can identify all changesets relating to a given issue.

>           * *Exception*: There is no need to refer to issues closed as
>             duplicates of other issues, when those other issues are
>             being referred to already.
>
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.

>    5. *Rule*: The references of rule 2 (and of recommendation 3 and 4,
>       if any) *must* be of the format KOKUA-/<issue ID>/, where
>       /<issue ID>/ is the Redmine issue number on your issue tracker
>       without the leading '#'.
>           * Example: KOKUA-123
>
A fixed format for the references makes searching for all issues related
to a given issue easier. (A single hg log -k call.)

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:

    * 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.
          o 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.)
    * The same goes of course also for others' repositories when they
      pull from us.
    * 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! ;-)


>    6. *Rule*: The references of rule 2 (and of recommendation 4, if
>       any) in the format of rule 5 *must* be located on the first line
>       of the commit message.
>
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: hg log
(without -v) displays just this line instead of the whole message.

When skimming over a log, I'd like to see the relevant issue IDs without
having to use -v (which would also give me lengthy change descriptions I
might not be interested in).

>           * *Recommendation*: Anywhere on that line is fine, but
>             prefer somewhere near its beginning.
>
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.

>           * Note: *Additional* 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 *one*
>             reference to each referred-to issue be on the first line
>             and of the mentioned format.
>
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.

Example:
"KOKUA-4000, KOKUA-2203: Check for nullpointers in llFooBar::bazHandler

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!"

>    7. *Rule*: The first line of the commit message *must* contain some
>       description of the change besides the ID references required above.
>
When skimming over a log, I'd like to be able to (roughly) figure out
what each changeset does, without having to use -v, -p 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-v, -p or
by looking at the issues.

>    8. *Recommendation*: To fulfill rule 7, describe in prose what the
>       specific changeset changes and (maybe on further lines) why. [...]
>
Well, that's the purpose of the commit message in general and especially
of its 'subject line'.

> [... (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.
This is to make rule 7 less scary to those who dislike writing. :-)
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.


Again, this all is meant as a base for discussion. Feedback is welcome.

Cheers,
Borun
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.kokuaviewer.org/pipermail/kokua-dev-kokuaviewer.org/attachments/20110824/b7986fa9/attachment-0002.htm>