EPICS Controls Argonne National Laboratory

Experimental Physics and
Industrial Control System

2002  2003  2004  2005  2006  2007  2008  2009  <20102011  2012  2013  2014  2015  2016  2017  2018  2019  2020  2021  2022  2023  2024  Index 2002  2003  2004  2005  2006  2007  2008  2009  <20102011  2012  2013  2014  2015  2016  2017  2018  2019  2020  2021  2022  2023  2024 
<== Date ==> <== Thread ==>

Subject: Re: Bazaar commit messages: style guide
From: Ralph Lange <[email protected]>
To: EPICS core-talk <[email protected]>
Date: Wed, 18 Aug 2010 11:28:07 -0400
 Andrew,

I would like to suggest two additions to that guide.


1. Prefix the summary line with the area that the commit addresses, followed by a colon and a space. I would see the area being one out of the directory names below base/src - these names are also being used as tags in bug reports. The libcom area might need one more identifier to be useful.

Examples

db: Fix off-by-one error in dbGetAddr()
libcom/timer: Add test for uninit'd user structure


2. The last paragraph of the commit message may be one or more "name: value" lines
Use this to mention any relation to bugs.

Examples

fixes: lp:595240
related: lp:615916


What do you think?
Ralph


On 17.08.2010 12:27, Andrew Johnson wrote:
In order to make Bazaar log messages readable in the future, I would ask all
committers to follow the style advice given below when writing commit messages
(some of these were new to me too).

Thanks,

- Andrew


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

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!
--------------------------------

Most text editors word wrap by default at the width of your terminal window,
often 80 characters. This becomes a problem when viewing commit messages
because VCS tools typically indent the message by a few whitespace characters,
and in some cases clip lines at the terminal width when viewing commit logs.
If you don't word wrap at all it looks even worse, and viewing the commit on
launchpad will result in an illegible very wide window.

Therefore, lines in commit messages must be word wrapped using hard returns at
70 characters.

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 that commit when
it later gets merged into Base.  Use 'bzr whoami' or set the BZR_EMAIL
environment variable.


Replies:
Re: Bazaar commit messages: style guide Andrew Johnson
References:
Bazaar commit messages: style guide Andrew Johnson

Navigate by Date:
Prev: Re: Fixed: Segfaults in 3.14 branch since merging ca-over-tcp Ralph Lange
Next: Re: Bazaar commit messages: style guide Andrew Johnson
Index: 2002  2003  2004  2005  2006  2007  2008  2009  <20102011  2012  2013  2014  2015  2016  2017  2018  2019  2020  2021  2022  2023  2024 
Navigate by Thread:
Prev: Bazaar commit messages: style guide Andrew Johnson
Next: Re: Bazaar commit messages: style guide Andrew Johnson
Index: 2002  2003  2004  2005  2006  2007  2008  2009  <20102011  2012  2013  2014  2015  2016  2017  2018  2019  2020  2021  2022  2023  2024 
ANJ, 02 Feb 2012 Valid HTML 4.01! · Home · News · About · Base · Modules · Extensions · Distributions · Download ·
· Search · EPICS V4 · IRMIS · Talk · Bugs · Documents · Links · Licensing ·