Messages in this thread | | | From | Ray Lee <> | Date | Wed, 15 Apr 2009 20:10:16 -0700 | Subject | Re: Fix quilt merge error in acpi-cpufreq.c |
| |
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.
| |