Commit messages should include four components
- The WHERE - a single word that categorizes and provides context for the commit and its message, followed by a colon (:). This is typically the name of the plugin being worked on, but sometimes might be something like Build: or Demos:
- The WHAT - a sufficient summary of the fix or change made (example: modified the foo to no longer bar), followed by a period (.)
- The WHY #Num - the ticket number with a #sign so Trac creates a hyperlink (example: #1234), followed by a hyphen/dash (-)
- The WHY Name - the name of the ticket. Notice this is different than summary of the fix. This is a short description of the issue (example: dialog: IE6 crashed when foo is set to bar)
- Combined into one, here's a full example:
- "Dialog: modified the foo to no longer bar. Fixed #1234 - dialog: IE6 crashed when foo is set to bar"
- \WHERE/:\------------- WHAT -------------/.\ WHY #Num /-\---------------- WHY Name ----------------/
Note: This style guide is part of our Bug Fixing Guide, which contains more information on:
- How to log a new issue
- How to verify a bug exists
- How to work on a new issue
- How to properly close an issue
- How to properly commit
Comments (6)
Jörn Zaefferer said
at 8:10 am on May 15, 2010
What if something is just related to a ticket, eg. a visual or unit test for a ticket? "Test for #xxx"?
Richard D. Worth said
at 1:17 pm on May 15, 2010
Sure. "Test for #xxx" or "Related to #xxx" or "Partial fix for #xxx". We'll likely set up some hook soon to look for 'fixed' or 'fixes' and automatically close the ticket if it's one of those. If it's something else we could just add a note/comment, not close it.
Carl Fürstenberg said
at 7:47 am on May 16, 2010
I think multi line commit messages should be preferred than single line messages. 50 character should be max for first line imo (that's what vim for example marks out).
Richard D. Worth said
at 10:48 am on May 16, 2010
There are tools in our chain (at least GitHub) that only display the first line depending on the context. So the four parts of the message detailed on this page, as laid out above, should be on the first line with no newlines. If additional detail is required, that could go on additional lines. Of course it should be additional detail about the same fix, as a separate fix warrants a separate commit.
Carl Fürstenberg said
at 11:13 am on May 16, 2010
The WHAT should be a short summary, as there is a reason why in some contexts only the first line is shown. Sufficient information yes, but not too much.
I think the "Why name" is unnecessary, bug number is enough imo.
Also suggest in your template to change "Fixed" to "Fixes:".
Richard D. Worth said
at 11:55 am on May 16, 2010
Agreed, the WHAT should be a short summary. Anything more than that should be on additional lines.
If I'm looking through a list of 20 commits, whether it's a commit log or a fork queue, I don't want to see 20 bug numbers, I want to see 20 bug numbers with the bug summary next to each. It also can serve as an extra QC check as every now and then someone will mistype the bug number.
The rest of the message is in past tense, that's why I wrote fixed instead of fixes. It also reads well as a status messages "Committer XXX fixed #1234 - ..." vs "Committer XXX fixes #1234 - ...". That said, I'll accept a commit with 'fixes' in the message. As I suggest in a comment above, no reason our hook can't handle both equally well.
You don't have permission to comment on this page.