Writing Good Commit Messages

Rule zero: “good” is defined by the standards of the project you're on. Have a -look at what the existing messages look like, and try to emulate that first -before doing anything else.

Having said that, here are some things that will help your commit messages be -useful later:

-
Treat the first line of the message as a one-sentence summary. Most SCM - systems have an “overview” command that shows shortened commit messages in - bulk, so making the very beginning of the message meaningful helps make - those modes more useful for finding specific commits. It's okay for this to - be a “what” description if the rest of the message is a “why” description.
-
-
Fill out the rest of the message with prose outlining why you made the - change. The guidelines for a good “why” message are the same as the - guidelines for good comments, but commit messages can be - signifigantly longer. Don't bother reiterating the contents of the change in - detail; anyone who needs that can read the diff themselves.
-
-
If you use an issue tracker (and you should), include whatever issue-linking - notes it supports right at the start of the message, where it'll be visible - even in shortlogs. If your tracker has absurdly long issue-linking syntax, - or doesn't support issue links in commits at all, include a short issue - identifier at the front of the message and put the long part somewhere out - of the way, such as on a line of its own at the end of the message.
-
-
Pick a tense and a mood and stick with them. Reading one commit with a - present-tense imperative message (“Add support for PNGs”) and another commit - with a past-tense narrative message (“Fixed bug in PNG support”) is - distracting.
-
-
If you need rich commit messages (links, lists, and so on), pick one markup - language and stick with it. It'll be easier to write useful commit - formatters if you only have to deal with one syntax, rather than four. - (Personally, I use Markdown on projects I control.)
-
- This also applies to line-wrapping: either hard-wrap everywhere, or - hard-wrap nowhere.
-

An Example

commit 842e6c5f41f6387781fcc84b59fac194f52990c7
-Author: Owen Jacobson <owen.jacobson@grimoire.ca>
-Date:   Fri Feb 1 16:51:31 2013 -0500
-
-    DS-37: Add support for privileges, and create a default privileged user.
-
-    This change gives each user a (possibly empty) set of privileges. Privileges
-    are mediated by roles in the following ways:
-
-    * Each user is a member of zero or more roles.
-    * Each role implies membership in zero or more roles. If role A implies role
-      B, then a member of role A is also a transitive member of role B. This
-      relationship is transitive: if A implies B and B implies C, then A implies
-      C. This graph should not be cyclic, but it's harmless if it is.
-    * Each role grants zero or more privileges.
-
-    A user's privileges are the union of all privileges of all roles the user is a
-    member of, either directly or transitively.
-
-    Obviously, a role that implies no other roles and grants no priveleges is
-    meaningless to the authorization system. This may be useful for "advisory"
-    roles meant for human consumption.
-
-    This also introduces a user with the semi-magical name '*admin' (chosen
-    because asterisks cannot collide with player-chosen usernames), and the group
-    '*superuser' that is intended to hold all privileges. No privileges are yet
-    defined.
-

- - - -

- - -comments powered by Disqus -

- - - - - -