OT: Favourite log message layout

From: Andy Parkins <andyparkins@gmail.com>
Date: Feb 28, 2007, 09:48 UTC
Message-ID: <200702280948.05391.andyparkins@gmail.com>
In-Reply-To: <Pine.LNX.4.64.0702271453030.12485@woody.linux-foundation.org>

On Tuesday 2007 February 27 23:02, Linus Torvalds wrote:

> I don't think the GNU style ChangeLog is particularly good. In fact, I
> think it has an unfortunate tendency (thanks to being per-file-log) to
> encourage people to commit unrelated changes and then explain them per
> file.

Me either; however, I do like per-file information. My own favoured format for log messages is (with all but the shortlog optional)

---- 8< ---- Short log message summarises changes in one line

Longer message summarises changes, perhaps with reasons for change and why this change fixes something.

file1.c
 * detailed description of change to this file
 * more changes

file2.c
 * detailed description of change to this file
---- >8 ----

That's not to say that this is an excuse to lump unrelated changes together, but it does allow one to say

 file1.c
  * Added function xyz()

 file2.c
  * Call new function xyz() to achieve clever feature

when it's appropriate. I've found this particularly useful in conjunction with git-blame. You find the revision that made a change in a particular file then the log message is easily searched to find the exact reasons for that change on that line in that file.

Perhaps I'm overly verbose though. I do like the sound of my own voice - even on log messages :-)

Andy

-- 
Dr Andy Parkins, M Eng (hons), MIET
andyparkins@gmail.com