[PATCH 1/2] Documentation/SubmittingPatches: Explain the rationale of git notes

[PATCH 1/2] Documentation/SubmittingPatches: Explain the rationale of git notes

[Stefan Beller]

This adds an explanation of why you want to have the --notes option
given to git format-patch.

Signed-off-by: Stefan Beller <sbeller@google.com>
---

Notes:
    > with optionally update Documentation/SubmittingPatches
    > to point at the file.
    
    That file actually talks about notes already.  I am sending
    two patches touching that file, one of them explaining
    the --notes workflow rationale and one of them just changing
    white spaces.
    
    A few weeks ago I wanted to patch format-patch to remove
    change ids. This is not needed any more for the git workflow
    as I disabled them and do not upload any patches to an optional
    Gerrit code review server anymore.
    
    I do like the workflow using --notes as well from a developers
    perspective as I take literally notes for my own sanity.
    I wonder if I should add a config format.notes = [default-off,
    always, on-if-non-empty] so I don't need always add --notes
    manually to the command line.
    
    Thanks,
    Stefan

 Documentation/SubmittingPatches | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index fa71b5f..16b5d65 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -176,7 +176,11 @@ 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. Git-notes
-can also be inserted using the `--notes` option.
+can also be inserted using the `--notes` option. If you are one
+of those developers who cannot write perfect code the first time
+and need multiple iterations of review and discussion, you are
+encouraged to use the notes to describe the changes between the
+different versions of a patch.
 
 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
-- 
2.2.0.31.gad78000.dirty

[PATCH] Documentation/SubmittingPatches: unify whitespace/tabs for the DCO

[Stefan Beller]

The Developers Certificate of Origin has a mixture of tabs and white
spaces which is annoying to view if your editor explicitly views white
space characters.

Signed-off-by: Stefan Beller <sbeller@google.com>
---
 Documentation/SubmittingPatches | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 16b5d65..6124f34 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -258,15 +258,15 @@ pretty simple: if you can certify the below:
             person who certified (a), (b) or (c) and I have not modified
             it.
 
-	(d) I understand and agree that this project and the contribution
-	    are public and that a record of the contribution (including all
-	    personal information I submit with it, including my sign-off) is
-	    maintained indefinitely and may be redistributed consistent with
-	    this project or the open source license(s) involved.
+        (d) I understand and agree that this project and the contribution
+            are public and that a record of the contribution (including all
+            personal information I submit with it, including my sign-off) is
+            maintained indefinitely and may be redistributed consistent with
+            this project or the open source license(s) involved.
 
 then you just add a line saying
 
-	Signed-off-by: Random J Developer <random@developer.example.org>
+        Signed-off-by: Random J Developer <random@developer.example.org>
 
 This line can be automatically added by Git if you run the git-commit
 command with the -s option.
-- 
2.2.0.31.gad78000.dirty

[PATCH 2/2] Documentation/SubmittingPatches: unify whitespace/tabs for the DCO

[Stefan Beller]

The Developers Certificate of Origin has a mixture of tabs and white
spaces which is annoying to view if your editor explicitly views white
space characters.

Signed-off-by: Stefan Beller <sbeller@google.com>
---

Notes:
    I'll also try to send it upstream to linux.

 Documentation/SubmittingPatches | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 16b5d65..6124f34 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -258,15 +258,15 @@ pretty simple: if you can certify the below:
             person who certified (a), (b) or (c) and I have not modified
             it.
 
-	(d) I understand and agree that this project and the contribution
-	    are public and that a record of the contribution (including all
-	    personal information I submit with it, including my sign-off) is
-	    maintained indefinitely and may be redistributed consistent with
-	    this project or the open source license(s) involved.
+        (d) I understand and agree that this project and the contribution
+            are public and that a record of the contribution (including all
+            personal information I submit with it, including my sign-off) is
+            maintained indefinitely and may be redistributed consistent with
+            this project or the open source license(s) involved.
 
 then you just add a line saying
 
-	Signed-off-by: Random J Developer <random@developer.example.org>
+        Signed-off-by: Random J Developer <random@developer.example.org>
 
 This line can be automatically added by Git if you run the git-commit
 command with the -s option.
-- 
2.2.0.31.gad78000.dirty

Re: [PATCH 2/2] Documentation/SubmittingPatches: unify whitespace/tabs for the DCO

[Junio C Hamano]

Stefan Beller <sbeller@google.com> writes:

> The Developers Certificate of Origin has a mixture of tabs and white
> spaces which is annoying to view if your editor explicitly views white
> space characters.
>
> Signed-off-by: Stefan Beller <sbeller@google.com>
> ---
>
> Notes:
>     I'll also try to send it upstream to linux.

Thanks.

>
>  Documentation/SubmittingPatches | 12 ++++++------
>  1 file changed, 6 insertions(+), 6 deletions(-)
>
> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> index 16b5d65..6124f34 100644
> --- a/Documentation/SubmittingPatches
> +++ b/Documentation/SubmittingPatches
> @@ -258,15 +258,15 @@ pretty simple: if you can certify the below:
>              person who certified (a), (b) or (c) and I have not modified
>              it.
>  
> -	(d) I understand and agree that this project and the contribution
> -	    are public and that a record of the contribution (including all
> -	    personal information I submit with it, including my sign-off) is
> -	    maintained indefinitely and may be redistributed consistent with
> -	    this project or the open source license(s) involved.
> +        (d) I understand and agree that this project and the contribution
> +            are public and that a record of the contribution (including all
> +            personal information I submit with it, including my sign-off) is
> +            maintained indefinitely and may be redistributed consistent with
> +            this project or the open source license(s) involved.
>  
>  then you just add a line saying
>  
> -	Signed-off-by: Random J Developer <random@developer.example.org>
> +        Signed-off-by: Random J Developer <random@developer.example.org>
>  
>  This line can be automatically added by Git if you run the git-commit
>  command with the -s option.

Re: [PATCH 1/2] Documentation/SubmittingPatches: Explain the rationale of git notes

[Junio C Hamano]

Stefan Beller <sbeller@google.com> writes:

> This adds an explanation of why you want to have the --notes option
> given to git format-patch.
>
> Signed-off-by: Stefan Beller <sbeller@google.com>
> ---
>
> Notes:
>     > with optionally update Documentation/SubmittingPatches
>     > to point at the file.
>     
>     That file actually talks about notes already.  I am sending
>     two patches touching that file, one of them explaining
>     the --notes workflow rationale and one of them just changing
>     white spaces.
>     
>     A few weeks ago I wanted to patch format-patch to remove
>     change ids. This is not needed any more for the git workflow
>     as I disabled them and do not upload any patches to an optional
>     Gerrit code review server anymore.
>     
>     I do like the workflow using --notes as well from a developers
>     perspective as I take literally notes for my own sanity.
>     I wonder if I should add a config format.notes = [default-off,
>     always, on-if-non-empty] so I don't need always add --notes
>     manually to the command line.
>     
>     Thanks,
>     Stefan
>
>  Documentation/SubmittingPatches | 6 +++++-
>  1 file changed, 5 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> index fa71b5f..16b5d65 100644
> --- a/Documentation/SubmittingPatches
> +++ b/Documentation/SubmittingPatches
> @@ -176,7 +176,11 @@ 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. Git-notes
> -can also be inserted using the `--notes` option.
> +can also be inserted using the `--notes` option. If you are one

Because the previous sentence is talking about the cover letter to
describe the overall series, it probably is a good idea to add
"after the three-dashes of each patch" after "... using the notes
option" for clarity, perhaps?

> +of those developers who cannot write perfect code the first time
> +and need multiple iterations of review and discussion, you are
> +encouraged to use the notes to describe the changes between the
> +different versions of a patch.

Perhaps s/you are encouraged to/you may want to/?  It might be
better to be even more explicit, e.g. "you may want to keep track of
the changes between the versions using the notes and then use
`--notes` when preparing the series for submission"?

>  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

Thanks.

Re: [PATCH 1/2] Documentation/SubmittingPatches: Explain the rationale of git notes

[Stefan Beller]

On Mon, Dec 22, 2014 at 9:55 AM, Junio C Hamano <gitster@pobox.com> wrote:
> Stefan Beller <sbeller@google.com> writes:
>
>> This adds an explanation of why you want to have the --notes option
>> given to git format-patch.
>>
>> Signed-off-by: Stefan Beller <sbeller@google.com>
>> ---
>>
>> Notes:
>>     > with optionally update Documentation/SubmittingPatches
>>     > to point at the file.
>>
>>     That file actually talks about notes already.  I am sending
>>     two patches touching that file, one of them explaining
>>     the --notes workflow rationale and one of them just changing
>>     white spaces.
>>
>>     A few weeks ago I wanted to patch format-patch to remove
>>     change ids. This is not needed any more for the git workflow
>>     as I disabled them and do not upload any patches to an optional
>>     Gerrit code review server anymore.
>>
>>     I do like the workflow using --notes as well from a developers
>>     perspective as I take literally notes for my own sanity.
>>     I wonder if I should add a config format.notes = [default-off,
>>     always, on-if-non-empty] so I don't need always add --notes
>>     manually to the command line.
>>
>>     Thanks,
>>     Stefan
>>
>>  Documentation/SubmittingPatches | 6 +++++-
>>  1 file changed, 5 insertions(+), 1 deletion(-)
>>
>> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
>> index fa71b5f..16b5d65 100644
>> --- a/Documentation/SubmittingPatches
>> +++ b/Documentation/SubmittingPatches
>> @@ -176,7 +176,11 @@ 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. Git-notes
>> -can also be inserted using the `--notes` option.
>> +can also be inserted using the `--notes` option. If you are one
>
> Because the previous sentence is talking about the cover letter to
> describe the overall series, it probably is a good idea to add
> "after the three-dashes of each patch" after "... using the notes
> option" for clarity, perhaps?

The previous sentence is talking about additional information,
which should not go into the commit message. (very similar to
the cover letter but just for one patch). It already mentions the place
"between the three dash lines and the diffstat."

>
>> +of those developers who cannot write perfect code the first time
>> +and need multiple iterations of review and discussion, you are
>> +encouraged to use the notes to describe the changes between the
>> +different versions of a patch.
>
> Perhaps s/you are encouraged to/you may want to/?  It might be
> better to be even more explicit, e.g. "you may want to keep track of
> the changes between the versions using the notes and then use
> `--notes` when preparing the series for submission"?

I did reword it to make it more obvious.

>
>>  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
>
> Thanks.

A paragraph before that change we have

    "git format-patch" command follows the best current practice to
    format the body of an e-mail message.

which makes me wonder if the notes are a best practice or may be
becoming a best practice. So maybe we want to default to add the notes
in format-patch instead of explicitly asking for it. But that's just an idea
suited for another patch.

Thanks

[PATCHv2] Documentation/SubmittingPatches: Explain the rationale of git notes

[Stefan Beller]

This adds more explanation of why you want to have the --notes option
given to git format-patch.

Signed-off-by: Stefan Beller <sbeller@google.com>
---

Notes:
    Changes v2:
     * s/you are encouraged to/you may want to/
     * a stronger hint to use the git notes and then
       --notes for format-patch.

 Documentation/SubmittingPatches | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index e3c942e..f42c607 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -177,7 +177,12 @@ 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. Git-notes
-can also be inserted using the `--notes` option.
+can also be inserted using the `--notes` option. If you are one
+of those developers who cannot write perfect code the first time
+and need multiple iterations of review and discussion, you may
+want to keep track of the changes between different versions of
+a patch using notes and then also use the `--notes` option when
+preparing the patch for submission.
 
 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
-- 
2.2.1.62.g3f15098

Re: [PATCHv2] Documentation/SubmittingPatches: Explain the rationale of git notes

[Eric Sunshine]

On Mon, Dec 29, 2014 at 12:42 PM, Stefan Beller <sbeller@google.com> wrote:
> This adds more explanation of why you want to have the --notes option
> given to git format-patch.
>
> Signed-off-by: Stefan Beller <sbeller@google.com>
> ---
> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> index e3c942e..f42c607 100644
> --- a/Documentation/SubmittingPatches
> +++ b/Documentation/SubmittingPatches
> @@ -177,7 +177,12 @@ 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. Git-notes
> -can also be inserted using the `--notes` option.
> +can also be inserted using the `--notes` option. If you are one
> +of those developers who cannot write perfect code the first time
> +and need multiple iterations of review and discussion, you may
> +want to keep track of the changes between different versions of
> +a patch using notes and then also use the `--notes` option when
> +preparing the patch for submission.

Perhaps this could be rephrased in a less derogatory fashion like this:

    ...material between the three dash line and the diffstat.
    For patches requiring multiple iterations of review and
    discussion, an explanation of changes between each iteration can
    be kept in Git-notes and inserted automatically following the
    three dash line via `git format-patch --notes`.

>  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
> --
> 2.2.1.62.g3f15098

Re: [PATCHv2] Documentation/SubmittingPatches: Explain the rationale of git notes

[Stefan Beller]

On Mon, Dec 29, 2014 at 3:18 PM, Eric Sunshine <sunshine@sunshineco.com> wrote:
> On Mon, Dec 29, 2014 at 12:42 PM, Stefan Beller <sbeller@google.com> wrote:
>> This adds more explanation of why you want to have the --notes option
>> given to git format-patch.
>>
>> Signed-off-by: Stefan Beller <sbeller@google.com>
>> ---
>> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
>> index e3c942e..f42c607 100644
>> --- a/Documentation/SubmittingPatches
>> +++ b/Documentation/SubmittingPatches
>> @@ -177,7 +177,12 @@ 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. Git-notes
>> -can also be inserted using the `--notes` option.
>> +can also be inserted using the `--notes` option. If you are one
>> +of those developers who cannot write perfect code the first time
>> +and need multiple iterations of review and discussion, you may
>> +want to keep track of the changes between different versions of
>> +a patch using notes and then also use the `--notes` option when
>> +preparing the patch for submission.
>
> Perhaps this could be rephrased in a less derogatory fashion like this:

This wasn't meant to be derogatory at all. It was more of subtle humor.
Sorry for the confusion.

If this is offensive in any way I'd rather go with your suggestion indeed.

>
>     ...material between the three dash line and the diffstat.
>     For patches requiring multiple iterations of review and
>     discussion, an explanation of changes between each iteration can
>     be kept in Git-notes and inserted automatically following the
>     three dash line via `git format-patch --notes`.
>
>>  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
>> --
>> 2.2.1.62.g3f15098

Re: [PATCHv2] Documentation/SubmittingPatches: Explain the rationale of git notes

[Junio C Hamano]

Stefan Beller <sbeller@google.com> writes:

>>> +can also be inserted using the `--notes` option. If you are one
>>> +of those developers who cannot write perfect code the first time
>>> +and need multiple iterations of review and discussion, you may
>>> +want to keep track of the changes between different versions of
>>> +a patch using notes and then also use the `--notes` option when
>>> +preparing the patch for submission.
>>
>> Perhaps this could be rephrased in a less derogatory fashion like this:
>
> This wasn't meant to be derogatory at all. It was more of subtle humor.
> Sorry for the confusion.
>
> If this is offensive in any way I'd rather go with your suggestion indeed.

I too found it very close to the borderline between being funny and
being unnecessarily condescending when I first read it and couldn't
tell which side of the line it was on.

It is not if the readers need multiple iterations to get things
perfect (most of us do, anyway).  It is if the readers already have
a good procedure to manage the changes (if they do, they do not need
us to making suggestion to use notes) or they are actively in search
of a good tool to add to their toolbox.  From that point of view,
Eric's rewrite does present a useful tool to keep track of changes
that the readers may want to consider in a lot tamer way.