On Tuesday 27 October 2009, Nicolas Pitre wrote: > Therefore, when composing a commit message text, it is a good idea to > include the following elements: > > 1) A short summary for the patch that is ideally 80 characters or less. > Good examples are: > > "Fix incorrect line endings"
And that one is interesting since it's also an example of a patch where the summary *suffices* ... > "SVF: fix parsing hex strings containing leading '0' characters" > > "ETM: rename registers, doc tweaks" Those two highlight another point: please tag the patch according to the subsystem it affects. That makes log summaries (the patch-per-line flavor) much more useful. > 2) An empty line. That's how Git distinguishes the summary line from > the main commit explanation text. Or ... "git am" will take $SUBJECT as the summary, and add this blank line automatically. Which serves a related goal: when someone sees a commit in the repository, they may want to see the discussion associated with that patch. > 3) Explanations on the commit. Here is the place to provide details > justifying the change, like a description of the issue, the way this > patch is solving it, any remaining issues after that patch is > applied, etc. Of course there are patches that are so trivial to > justify any more explanation other than what was already provided in > the summary line (the "Fix incorrect line endings" being one > such example). But most patches certainly deserves to be justified > with more than one line of text as can be seen from many email > threads following their initial posts on the list. > > There are good examples in the repository already. So please take some > time to look at the output from 'git log' and think about making that > log understandable to people other than the patch author by following > those good examples. > Also makes "git whatchanged foo.c" be more useful ... you can then read the history in the file where you isolated the bug, and then "aha! this patch probably uncovered/introduced/... the bug I just ran into!". And only *then* look at details. - Dave _______________________________________________ Openocd-development mailing list [email protected] https://lists.berlios.de/mailman/listinfo/openocd-development
