patch, 2 partsDocumentation/SubmittingPatches: Explain the rationale of git notes

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

> 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

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

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

> 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

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