Re: Fix quilt merge error in acpi-cpufreq.c

[Theodore Tso]

On Thu, Apr 16, 2009 at 10:57:05AM +0930, Rusty Russell wrote:
> Ingo wants them.  Example:
> 
> 	lguest: don't expect linear addresses in gdt pvops
> 
> 	Impact: fix guest crash 'lguest: bad read address 0x4800000 len 256'
> 
> What's more important in the subject line?  That it fixes a crash, or what it
> does?

Well, consider that 2 or 3 months later, when we're trying to find a
potential commit (say, because we're trying to find a potential fix
that needs to be forward ported to a distro kernel, or some such), the
initial summary line is what is going to be visible in gitk or via
"git log --oneline" (or "git log --pretty=oneline --abbrev-commit" for
older git versions).

So when I try to create git log messages, I try to make the first line
useful for folks who might be sorting through potentially thousands of
patches via gitk or git log --oneline.  So I might do something like

lguest: fix crash caused by expecting linear address in gdt pvops

and then making sure the body of the message goes into detail about
the oops message so that someone who is searching "git log" might find
the commit.  I also try to include relevant bugzilla numbers (for
distro's as well as the kernel bugzilla system).[1]

I think it was you who once quoted Will Strunk, "Always write with
deep sympathy for the reader"?  This definitely applies to git commit
messages, both the initial one-line summary as well as the body.

[1] I tend to use "Addresses-Debian-bug: #12345" in e2fsprogs git
repository, but the convention in the kernel commit logs seems to be
to use the URL to the bugzilla entry.  Since it's stuff that's
intended to be grep'ed, I put it at the end of the commit body, just
before the Signed-off-by: messages.

						- Ted

P.S.  One thing wihch I'd like to suggest is for folks to use "fix
lock ordering" instead of "fix lockdep warning".  I've been guilty of
using "lockdep warning" mmyself, and I've realized that when searching
to see if a reported hang might have been fixed, the brain has a
tendency to skip over a summary line that says "warning"; and a commit
that fixes a lockdep warning is more serious, than say, for example,
fixing some whining warning message from gcc.
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/