Re: [PATCH] Doc format-patch: clarify --notes use case
On Thu, Oct 25, 2012 at 11:48:04PM +0100, Philip Oakley wrote: > >+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? Yeah, I think just saying "notes.rewrite" is better. The notes.rewrite.* entry does point to rewriteRef, but there is no point in giving the user a trail of "see also" breadcrumbs when we can just point them to the area as a whole. I updated it to this: diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 066dc8b..259dce4 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 options in linkgit:git-notes[1] to use this workflow). --[no]-signature=:: Add a signature to each message produced. Per RFC 3676 the signature -- 1.8.0.3.g3456896 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Doc format-patch: clarify --notes use case
From: "Jeff King" Sent: Thursday, October 25, 2012 11:25 AM 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. 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. 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? 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 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] Doc format-patch: clarify --notes use case
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 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: 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). --[no]-signature=:: Add 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 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH] Doc format-patch: clarify --notes use case
Remove double negative, and include the repeat usage across versions of a patch series. Signed-off-by: Philip Oakley --- Documentation/git-format-patch.txt | 11 --- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 066dc8b..751009c 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -196,13 +196,10 @@ will want to ensure that threading is disabled for `git send-email`. 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. The notes can be maintained +between versions of the patch series. You can also edit the output of +format-patch before sending. --[no]-signature=:: Add a signature to each message produced. Per RFC 3676 the signature -- 1.7.11.msysgit.1 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
