Re: [PATCH] Doc format-patch: clarify --notes use case
From: "Jeff King" <peff@peff.net> Sent: Thursday, October 25, 2012 11:25
AM
Show 19 quoted lines
> On Sun, Oct 21, 2012 at 10:34:10PM +0100, Philip Oakley wrote:
>
>> The expected use case of this is to write supporting explanation for
>> -the commit that does not belong to the commit log message proper
>> -when (or after) you create the commit, and include it in your patch
>> -submission. But if you can plan ahead and write it down, there may
>> -not be a good reason not to write it in your commit message, and if
>> -you can't, you can always edit the output of format-patch before
>> -sending it out, so the practical value of this option is somewhat
>> -dubious, unless your workflow is broken.
>> +the commit, that does not belong to the commit log message proper,
>> +and include it with the patch submission. The notes can be
>> maintained
>> +between versions of the patch series. You can also edit the output
>> of
>> +format-patch before sending.
>
> I found the "you can also" slightly awkward here, as it was not clear
> why it was mentioned.
I was trying to catch what I think Junio was trying to say about 'writing it down' and 'can always edit the output' but wasn't exactly sure how to read it.
Show 8 quoted lines
>I think the intent is "this is an alternative that
> does not involve the notes workflow", but it is not clear from the
> text
> why you would prefer the notes workflow. Here is what I queued
> instead,
> which tires to clarify that, and also mentions that this workflow
> needs
> additional setup to track rewritten commits:
Your version below captures the intent. <Ack>
Show 25 quoted lines
>
> diff --git a/Documentation/git-format-patch.txt
> b/Documentation/git-format-patch.txt
> index 066dc8b..750b3fa 100644
> --- a/Documentation/git-format-patch.txt
> +++ b/Documentation/git-format-patch.txt
> @@ -196,13 +196,12 @@ The expected use case of this is to write
> supporting explanation for
> after the three-dash line.
> +
> The expected use case of this is to write supporting explanation for
> -the commit that does not belong to the commit log message proper
> -when (or after) you create the commit, and include it in your patch
> -submission. But if you can plan ahead and write it down, there may
> -not be a good reason not to write it in your commit message, and if
> -you can't, you can always edit the output of format-patch before
> -sending it out, so the practical value of this option is somewhat
> -dubious, unless your workflow is broken.
> +the commit that does not belong to the commit log message proper,
> +and include it with the patch submission. While one can simply write
> +these explanations after `format-patch` has run but before sending,
> +keeping them as git notes allows them to be maintained between
> versions
> +of the patch series (but see the discussion of the `notes.rewrite.*`
> +configuration in linkgit:git-notes[1] to use this workflow).
Should the notes.rewriteRef also be mentioned (not part of .*), which is at the end of the notes configuration and that it must be set may be missed by readers? Perhaps "the 'notes.rewrite' configurations", dropping the .* and making it plural?
Show 10 quoted lines
> a signature to each message produced. Per RFC 3676 the signature
>
>
> I've queued that and your other patches on top of
> jc/prettier-pretty-note.
>
> -Peff
>
>
> -----
Philip Oakley