[PATCH] Doc SubmittingPatches: Mention --notes option after "cover letter"

[PATCH] Doc SubmittingPatches: Mention --notes option after "cover letter"

[Philip Oakley]

The git format-patch --notes option can now insert the commit notes
after the three dashes. Mention this after the regular cover letter
guidance for submitting patches.

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 Documentation/SubmittingPatches | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 0dbf2c9..3d8b2fe 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -179,7 +179,8 @@ message starts, you can put a "From: " line to name that person.
 
 You often want to add additional explanation about the patch,
 other than the commit message itself.  Place such "cover letter"
-material between the three dash lines and the diffstat.
+material between the three dash lines and the diffstat. Git-notes
+can also be inserted using the `--notes` option.
 
 Do not attach the patch as a MIME attachment, compressed or not.
 Do not let your e-mail client send quoted-printable.  Do not let
-- 
1.7.11.msysgit.1

[PATCH] Doc User-Manual: Patch cover letter, three dashes, and --notes

[Philip Oakley]

Show that git format-patch can have a cover letter, include patch
commentary below the three dashes, and notes can also be
included.

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 Documentation/user-manual.txt | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 85651b5..d918c53 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1787,6 +1787,11 @@ $ git format-patch origin
 will produce a numbered series of files in the current directory, one
 for each patch in the current branch but not in origin/HEAD.
 
+`git format-patch` can include an initial "cover letter". You can insert
+a commentary on individual patches using a three dash line after the
+commit message, and before the patch itself. `git format-patch --notes`
+(v1.8.1) will include the commit's notes in the similar manner.
+
 You can then import these into your mail client and send them by
 hand.  However, if you have a lot to send at once, you may prefer to
 use the linkgit:git-send-email[1] script to automate the process.
-- 
1.7.11.msysgit.1

Re: [PATCH] Doc User-Manual: Patch cover letter, three dashes, and --notes

[Jeff King]

On Sun, Oct 21, 2012 at 10:34:08PM +0100, Philip Oakley wrote:

> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index 85651b5..d918c53 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -1787,6 +1787,11 @@ $ git format-patch origin
>  will produce a numbered series of files in the current directory, one
>  for each patch in the current branch but not in origin/HEAD.
>  
> +`git format-patch` can include an initial "cover letter". You can insert
> +a commentary on individual patches using a three dash line after the
> +commit message, and before the patch itself. `git format-patch --notes`
> +(v1.8.1) will include the commit's notes in the similar manner.

I'd rather not mention a version number here, as we do not yet know
which version (if any) will contain the feature. Besides, we write our
documentation to match the current version, so as long as this is queued
on top of the new code, I do not see any reason to mention a version at
all.

I'll tweak it while queueing.

-Peff

Re: [PATCH] Doc User-Manual: Patch cover letter, three dashes, and --notes

[Philip Oakley]

From: "Jeff King" <peff@peff.net> Sent: Thursday, October 25, 2012 11:26 
AM
> On Sun, Oct 21, 2012 at 10:34:08PM +0100, Philip Oakley wrote:
>
>> diff --git a/Documentation/user-manual.txt 
>> b/Documentation/user-manual.txt
>> index 85651b5..d918c53 100644
>> --- a/Documentation/user-manual.txt
>> +++ b/Documentation/user-manual.txt
>> @@ -1787,6 +1787,11 @@ $ git format-patch origin
>>  will produce a numbered series of files in the current directory, 
>> one
>>  for each patch in the current branch but not in origin/HEAD.
>>
>> +`git format-patch` can include an initial "cover letter". You can 
>> insert
>> +a commentary on individual patches using a three dash line after the
>> +commit message, and before the patch itself. `git 
>> format-patch --notes`
>> +(v1.8.1) will include the commit's notes in the similar manner.
>
> I'd rather not mention a version number here, as we do not yet know
> which version (if any) will contain the feature. Besides, we write our
> documentation to match the current version, so as long as this is 
> queued
> on top of the new code, I do not see any reason to mention a version 
> at
> all.

I'd included it because of the manual's title caveat "(for version 1.5.3 
or newer)", which I'd somehow thought was the matching date for the 
majority of text, hence my inclusion of the version. Begs the question 
what happened back then ;-)

>
> I'll tweak it while queueing.

Thank you.

>
> -Peff
> --

[PATCH] Doc notes: Include the format-patch --notes option

[Philip Oakley]

git format-patch gained a --notes option. Tell the notes user.

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 Documentation/git-notes.txt | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
index b95aafa..46ef046 100644
--- a/Documentation/git-notes.txt
+++ b/Documentation/git-notes.txt
@@ -39,6 +39,10 @@ message stored in the commit object, the notes are indented like the
 message, after an unindented line saying "Notes (<refname>):" (or
 "Notes:" for `refs/notes/commits`).
 
+Notes can also be added to patches prepared with `git format-patch` by
+using the `--notes` option. Such notes are added as a patch commentary
+after a three dash separator line.
+
 To change which notes are shown by 'git log', see the
 "notes.displayRef" configuration in linkgit:git-log[1].
 
-- 
1.7.11.msysgit.1

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

[Philip Oakley]

Remove double negative, and include the repeat usage across
versions of a patch series.

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 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=<signature>::
 	Add a signature to each message produced. Per RFC 3676 the signature
-- 
1.7.11.msysgit.1

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

[Jeff King]

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=<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

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

[Philip Oakley]

From: "Jeff King" <peff@peff.net> 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. <Ack>
>
> 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 

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

[Jeff King]

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=<signature>::
 	Add a signature to each message produced. Per RFC 3676 the signature
-- 
1.8.0.3.g3456896