Re: [PATCH] Doc format-patch: clarify --notes use case

From: Philip Oakley <philipoakley@iee.org>
Date: Oct 25, 2012, 22:48 UTC
Message-ID: <7427D8D31835443F96156C24D3EB6A5A@PhilipOakley>
In-Reply-To: <20121025102527.GO8390@sigill.intra.peff.net>

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