[Building Sakai] Commit messages - a humble little plea

[Noah Botimer]

Hello folks,

A trend I've noticed is the shortening of commit messages, to the point of simply being a JIRA issue number. There is an up-side here: I don't remember the last real commit I saw without a JIRA ticket referenced. However, the downside is significant in assuming that this is sufficient.

Take, for example, examining the history of a couple of branches to find when something was introduced. Common cases of this are cherry-picking a feature and porting a bug fix. I won't belabor all of the hassle, but mention a few points:

First, each JIRA ticket must be called up individually to see what the intent was (set aside the topic of issue titles, which could be better generally). Second, there are often multiple commits against a ticket, sometimes interleaved with others, so the task often includes closely analyzing multiple diffs just to divine the intent. Third, there are occasionally errors in the reference or multiple issues combined in a commit, making it very difficult to track in either direction (from JIRA or Subversion).


So, my simple request follows:

Could we please try to include a brief summary of what action is being taken with each commit? If the change is non-trivial, please also include some details of what was introduced, changed, or removed.


JIRA is great, but the one real truth is the source revision history. If you are committing something, please tell the historical record what you were doing.

Although it has some Git specifics, this is a very nice guideline: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

Thanks,
-Noah

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://collab.sakaiproject.org/pipermail/sakai-dev/attachments/20120214/8b08329f/attachment.html