On Tue, 27 Oct 2009, David Brownell wrote:
> On Monday 26 October 2009, Nicolas Pitre wrote:
> > Here are 3 patches to fix all the remaining issues I've encountered with
> > single-step support and Thumb mode.
> >
> > [PATCH 1/3] call thumb_pass_branch_condition() only for actual branch
> > opcodes
> > [PATCH 2/3] allow proper single stepping of Thumb BL and BLX instructions
> > [PATCH 3/3] fix Thumb mode handling when single-stepping register based
> > branch insns
>
> Merged all three ...
>
> Thanks for both the patches, and the good patch comments.
> I like having those. :)
I do too. Long tradition of patch contributions to some other Open
Source projects. See for example one of my best here:
http://git.kernel.org/?p=git/git.git;a=commit;h=0e8189e270
While the above is quite an extreme example, I still do think that patch
contributors to OpenOCD should be a bit more verbose in their commit
messages. Without naming anyone, some commits have extremely light
messages which are rather useless without actually looking at the patch
directly. And I know that those unamed individuals have good writing
skills given their track records on this mailing list. I hope those
people know who they are and will consider this as a gentle request to
improve their patch logs.
Now... People might be unaware of the fact that Git interprets the first
line of a commit message a bit specially. It is used by tools such as
shortlog or format-patch to provide a subject line or a short summary.
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"
"SVF: fix parsing hex strings containing leading '0' characters"
"ETM: rename registers, doc tweaks"
2) An empty line. That's how Git distinguishes the summary line from
the main commit explanation text.
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.
Nicolas
_______________________________________________
Openocd-development mailing list
[email protected]
https://lists.berlios.de/mailman/listinfo/openocd-development
