View source for Style Guide for Bazaar commit messages

The text of a commit log message will most likely survive for many years as a permanent description of the change it relates to. There are some conventions that Bazaar and related tools make use of when processing and displaying these messages, thus we provide the following style advice for EPICS developers writing a commit message.


=== Set your user id! ===

If you make a commit to a local branch before you've told Bazaar what your
name and email address is, it will make a guess and record that in the commit,
and from then on that user id will be forever associated with the commit when
it later gets merged into Base.  Use <tt>bzr whoami</tt> or set the <tt>BZR_EMAIL</tt> environment variable to tell Bazaar who you are.


=== Max message width 70 characters! ===

Many editors will word wrap text files using soft returns at the width of your terminal window, i.e. they do not insert a newline into the file at the wrap position at all. This is unfortunately also true of the Bazaar GUI tools, which give no warning if you write long single-line paragraphs.

This becomes a problem when viewing commit such messages with long lines. The command-line tool <tt>bzr log</tt> indents commit messages by a few white-space characters, and if you have Bazaar's <tt>pager</tt> plugin installed the <tt>less</tt> program will clip the lines to the terminal width (the user can scroll right to view more, but <tt>less</tt> gives no indication of this). Similarly viewing the commit on launchpad results in a very wide window.

Therefore, lines in commit messages should normally be word wrapped using hard returns at 70 characters or less.


=== 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 <tt>--line</tt> output to <tt>bzr log</tt>, etc. So a descriptive yet concise first line is important.

For really trivial fixes a single line is sufficient, but for more comprehensive changes please add a long comment, i.e. the summary 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 descriptive text of the revision comment.

Remember when writing that text that people use commit messages in different ways for different purposes.  Usually they do <tt>bzr log</tt> for the whole tree, so the commit message must provide a high level perspective of the change, but sometimes they use <tt>bzr log <i>filename</i></tt> to see all the
revisions which affected a particular file, in which case they're probably looking for detail.

If you are working on a branch which will later be merged into the main development trunk it is appropriate to provide more detailed commit messages for the individual branch commits and the higher level description for the branch merge.


=== Suggestions to improve readability ===

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.

If your commit only affects a particular section of the EPICS Base source tree, it can be helpful to prefix the summary line with the area affected, for example:
 db: Fix off-by-one error in dbGetAddr()
 libCom/timer: Add test for uninit'd user structure

Feel free to add 'name: value' lines to the bottom of your message if there is additional information that is most sensibly provided this way such as references to related launchpad bug numbers.  If a commit fixes a registered bug though you should still commit using the <tt>--fixes lp:''nnn''</tt> option to record that fact for launchpad's benefit.