4408 shaares
@Lenny qu'en penses-tu ?
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 -0500DS-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.