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

[Ray Lee <ray-lk@madrabbit.org>]

On Wed, Apr 15, 2009 at 7:00 PM, Rusty Russell <rusty@rustcorp.com.au> wrote:
> Anyone want to try to write a guide on writing good commit messages?

To me at least, this is no different than journalism (a commit message
is reporting on the facts, right?). So one can get some rough guidance
from thinking about who, what, where, when, why, how.


- Who is doing the work (from: lines)
- who will benefit from it. (ie, 'scope')

- What is the intended result? (feature? Bug-fix? Clean-up of the
foundations to prepare for future work?)
- What are you *doing*? (Not how -- which is the patch -- but what: a
human-understandable description of the patch.)

- Where is the feature or bug-fix needed or wanted? (Particular
laptops? hardware that is yet to hit the market? And -stable? -head?)

- When does the patch need to be applied? (This merge window, next
cycle, or as soon as possible for a root hole? After another set of
patches?)

- Why was it done *this* way, instead of another?
- Why does mainline want this? (For features. Bug fixes are self-explanatory.)

- how it was tested or validated (tested-by:, reviewed-by: tags).
- how it was implemented (which is satisfied by the patch itself)


Obviously not every patch needs all that crap. But every patch
*series* should probably have some thought put into all those, and the
ones that aren't obvious from the patch should be mentioned. The
trick, of course, is varying levels of 'obvious.' The measure of
'obvious' for journal articles is "someone who is versed in all the
necessary skills, but unfamiliar with the specifics of the topic."

Don't get me wrong, I don't want changelogs to be mini versions of war
and peace. But thinking about the above can put one in a better
context to then sit down and write a *nice* changelog.