[kokua-dev] Referring to Redmine issues in commit messages / Suggestion for a policy on commit messages

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

Aloha!

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
/how/ we refer to them. I think we /should/ 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
"http://redmine.kokuaviewer.org/issues/123" one would have to search for
all these combinations to find all related changesets.

There are also some other aspects of commit messages that could benefit
from some uniformity and rules.

Therefore I'd like to suggest the following policy:

(If this becomes an actual policy, rules would be mandatory to follow
while recommendations would be mere suggestions on what to do when unsure.)

   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.
   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.
   4. *Recommendation*: A changeset that fixing, implementing or
      relating to *several* issues *should* refer to all of them.
          * *Exception*: There is no need to refer to issues closed as
            duplicates of other issues, when those other issues are
            being referred to already.
   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
   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.
          * *Recommendation*: Anywhere on that line is fine, but prefer
            somewhere near its beginning.
          * 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.
   7. *Rule*: The first line of the commit message *must* contain some
      description of the change besides the ID references required above.
   8. *Recommendation*: 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.


    Rationale

Message is already rather long, so I'll follow up with the rationale for
the suggested rules and recommendations above in a separate message.


    Food for thought

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.


    Disclaimer


      This is not a policy, yet.

It's just a /suggestion/ 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.


      I don't think you're all dumb.

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.


      I don't think you're doing it all wrong.

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.


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.

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