Style guide: Commit Messages
It might seem a bit anal to ask people to follow certain conventions when writing their commit messages, but reading code history is a big part of debugging, and its a lot easier when things are consistent. So, please keep the following in mind:
Complete ideas preferred over one-liners
I’d prefer patches that are complete and comprehensive; one liner bug fixes are fine when necessary (ie, if that’s all it is) but if, say, you’re adding support for a new distro to the top level configure script, commit it as one complete patch rather than 5 small ones.
Of course at slightly larger levels of aggregation, series of patches chain
together, and that’s what branches are for. It’s tempting to try and ensure
that the eventual
bzr viz graph looks pretty, but don’t worry about it.
Branches are ultimately just a mechanism for shipping code around between
developers and we end up doing merges several times a day. I’m not really that
concerned about what the eventual branch tree ends up looking like, so just
concentrate on doing your work and we’ll let Bazaar take care of things
Summary line and revision text
Bazaar, like all other modern VCS tools, uses the first line of the commit
message as the summary which appears in email Subject: lines, the
bzr log, etc. So a descriptive yet concise first line is
For really trivial fixes, that single line as patch name is sufficient; but for more comprehensive patches please add a long comment (ie the subject line plus some prose describing what you’re up to. It doesn’t have to be perfect.
Put a single blank line between your summary line and the paragraphs you write as the main descriptive text of the revision comment.
Remember that years from now someone will do
bzr log filename and all the
revisions which affected that one file will show. So if you can, try to keep
commits on-topic; you don’t have to mention every last little change but try
your best to summarize the impact on major files if they’re somewhat
tangential to the main thrust of the rest of the commit.
Max message width 70 characters!
One problem with standard text editor is that they word wrap at a default of the normal terminal width, 80 characters. This is a problem when viewing commit messages because VCS tools typically indent the message by a few whitespace characters, resulting in insanely ugly wrapping when viewing commit logs in a terminal window.
Therefore, lines in commit messages must be no longer than 70 characters.
I forgot once and it looks stupid: see
bzr log --short -r 14. Too late now.
But to prevent this from happening again, try and ensure your editor knows
about the width limit. Vim users can put the following fragment in their
if expand("%:t") =~ "^bzr_log*" set textwidth=70 set filetype=none syn match commitComment "^#.*" hi link commitComment Comment endif
While you’re at it, you might want
if expand("%:e") == "java" set nowrap set ts=4 endif
to make sure a casual edit of a Java source file doesn’t mess it up.
Set your user id!
Keeping the integrity of the author history is important so that you get credit for your work. When you make a commit and subsequently send it to us in a bundle, we (and the rest of the world) sees who the author of each commit was. That’s terrific, but we do want to keep it professional for both aesthetic and legal reasons. So, one thing that we require is that the name and email address of the author be properly set. One of the following will take care of it:
bzr’s global configuration file
If you put
[DEFAULT] email = George Jones <firstname.lastname@example.org>
~/.bazaar/bazaar.conf file, it will be set for all branches and you
won’t have to think about it ever again.
Or you can run the
bzr whoami command as follows:
$ bzr whoami 'George Jones <email@example.com>'
Don’t forget the single quote to escape those angle brackets!
Or, you can use the
BZR_EMAIL environment variable:
$ export BZR_EMAIL='George Jones <firstname.lastname@example.org>'
Whichever you choose, please take the time to do this properly. It will ensure that the patch you send is properly attributed and that you will retain the full credit you deserve for your contribution. Patches that are not properly identified will not be accepted.
And if you try to tell me that your name is George Jones and that you work at
example.com, I will hit you with a large mallet.
Originally written by Andrew Cowie 2 Dec 06. Last modified 23 Apr 08.