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: Bazaar commit messages: style guide
From: Andrew Johnson <[email protected]>
To: "EPICS core-talk" <[email protected]>
Date: Tue, 17 Aug 2010 11:27:55 -0500
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.

-- 
The best FOSS code is written to be read by other humans -- Harald Welte



Replies:
Re: Bazaar commit messages: style guide Ralph Lange

Navigate by Date:
Prev: Re: Fixed: Segfaults in 3.14 branch since merging ca-over-tcp Ralph Lange
Next: devLib extensions review and testing request Davidsaver, Michael
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: Re: FW: Fixed: Segfaults in 3.14 branch since merging ca-over-tcp Andrew Johnson
Next: Re: Bazaar commit messages: style guide Ralph Lange
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 ·