[PATCH] Documentation: update git pull info in SubmittingPatches

[PATCH] Documentation: update git pull info in SubmittingPatches

[Paul Gortmaker]

The info in this section was overdue for an update; it had manual
individual steps listed for collecting the information that a
pull request should contain, and no mention of having a proper
overall summary in the pull request that could be used for a
merge commit.

There are other chunks of this file that need updates to match
current git workflows, but giant wholesale updates are more likely
to get caught up in bike shedding discussions over small details,
so lets start somewhere and attack the problem piece-wise.

Signed-off-by: Paul Gortmaker <paul.gortmaker@windriver.com>

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 6e97e73..6102da9 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -590,33 +590,32 @@ See more details on the proper patch format in the following
 references.
 
 
-16) Sending "git pull" requests  (from Linus emails)
-
-Please write the git repo address and branch name alone on the same line
-so that I can't even by mistake pull from the wrong branch, and so
-that a triple-click just selects the whole thing.
-
-So the proper format is something along the lines of:
-
-	"Please pull from
-
-		git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus
-
-	 to get these changes:"
-
-so that I don't have to hunt-and-peck for the address and inevitably
-get it wrong (actually, I've only gotten it wrong a few times, and
-checking against the diffstat tells me when I get it wrong, but I'm
-just a lot more comfortable when I don't have to "look for" the right
-thing to pull, and double-check that I have the right branch-name).
-
-
-Please use "git diff -M --stat --summary" to generate the diffstat:
-the -M enables rename detection, and the summary enables a summary of
-new/deleted or renamed files.
-
-With rename detection, the statistics are rather different [...]
-because git will notice that a fair number of the changes are renames.
+16) Sending "git pull" requests
+
+For a long time now, the "git request-pull" command has existed,
+and gives a uniform pre-canned text with all the expected information
+within it.  Use this as the basis of your pull request e-mail, and
+prefix it with a sensible description of what the overall series
+of commits achieves.  Assume that this text will be used by the
+maintainer in their merge commit of your changes, and hence be part
+of the git history, just like the changelog of each commit.  Use
+the triple dash described above to separate the merge commit text
+in the top of your mail from the output from "git request-pull".
+
+You are strongly discouraged against manually creating your own
+pull request text.  Doing so just increases the odds of having
+a typo in the repo location, the branch name, or other missing
+information.  In addition to creating all the required text output,
+the command also validates that your commits are actually reachable
+at the specified location, ensuring you don't waste the maintainer's
+time with having to hunt around trying find the location that you
+really meant.
+
+Your mail subject should be prefixed with "[GIT PULL]" and also
+mention the subsystem it is for, and if possible a very brief
+theme of what the changes achieve, e.g.
+
+   "[GIT PULL] x86: Remove uniprocessor support"
 
 -----------------------------------
 SECTION 2 - HINTS, TIPS, AND TRICKS
-- 
1.8.1.2

Re: [PATCH] Documentation: update git pull info in SubmittingPatches

[Randy Dunlap]

On 07/15/13 14:18, Paul Gortmaker wrote:
> The info in this section was overdue for an update; it had manual
> individual steps listed for collecting the information that a
> pull request should contain, and no mention of having a proper
> overall summary in the pull request that could be used for a
> merge commit.
> 
> There are other chunks of this file that need updates to match
> current git workflows, but giant wholesale updates are more likely
> to get caught up in bike shedding discussions over small details,
> so lets start somewhere and attack the problem piece-wise.
> 
> Signed-off-by: Paul Gortmaker <paul.gortmaker@windriver.com>

Did some "git <command>" create this patch?
It is missing <quote>
  - A marker line containing simply "---".
</quote> just after the S-O-B line.


> 
> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> index 6e97e73..6102da9 100644
> --- a/Documentation/SubmittingPatches
> +++ b/Documentation/SubmittingPatches
> @@ -590,33 +590,32 @@ See more details on the proper patch format in the following
>  references.
>  
>  
> -16) Sending "git pull" requests  (from Linus emails)
> -
> -Please write the git repo address and branch name alone on the same line
> -so that I can't even by mistake pull from the wrong branch, and so
> -that a triple-click just selects the whole thing.
> -
> -So the proper format is something along the lines of:
> -
> -	"Please pull from
> -
> -		git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus
> -
> -	 to get these changes:"
> -
> -so that I don't have to hunt-and-peck for the address and inevitably
> -get it wrong (actually, I've only gotten it wrong a few times, and
> -checking against the diffstat tells me when I get it wrong, but I'm
> -just a lot more comfortable when I don't have to "look for" the right
> -thing to pull, and double-check that I have the right branch-name).
> -
> -
> -Please use "git diff -M --stat --summary" to generate the diffstat:
> -the -M enables rename detection, and the summary enables a summary of
> -new/deleted or renamed files.
> -
> -With rename detection, the statistics are rather different [...]
> -because git will notice that a fair number of the changes are renames.
> +16) Sending "git pull" requests
> +
> +For a long time now, the "git request-pull" command has existed,
> +and gives a uniform pre-canned text with all the expected information
> +within it.  Use this as the basis of your pull request e-mail, and
> +prefix it with a sensible description of what the overall series
> +of commits achieves.  Assume that this text will be used by the
> +maintainer in their merge commit of your changes, and hence be part
> +of the git history, just like the changelog of each commit.  Use
> +the triple dash described above to separate the merge commit text
> +in the top of your mail from the output from "git request-pull".
> +
> +You are strongly discouraged against manually creating your own

                    discouraged from
(I would say, but no big deal.)

> +pull request text.  Doing so just increases the odds of having
> +a typo in the repo location, the branch name, or other missing
> +information.  In addition to creating all the required text output,
> +the command also validates that your commits are actually reachable
> +at the specified location, ensuring you don't waste the maintainer's
> +time with having to hunt around trying find the location that you
> +really meant.
> +
> +Your mail subject should be prefixed with "[GIT PULL]" and also
> +mention the subsystem it is for, and if possible a very brief
> +theme of what the changes achieve, e.g.
> +
> +   "[GIT PULL] x86: Remove uniprocessor support"

Lots of pull requests $Subject line also includes a kernel version number
that the pull is for, e.g.,

[GIT pull] x86 updates for 3.11

I find that helpful in searching.  IOW, I would prefer to see that instead
of 12 emails with the same subject of

[GIT pull] x86 updates

for kernel versions 3.0 thru 3.11.

>  
>  -----------------------------------
>  SECTION 2 - HINTS, TIPS, AND TRICKS
> 


-- 
~Randy

Re: [PATCH] Documentation: update git pull info in SubmittingPatches

[Paul Gortmaker]

On 13-07-15 05:31 PM, Randy Dunlap wrote:
> On 07/15/13 14:18, Paul Gortmaker wrote:
>> The info in this section was overdue for an update; it had manual
>> individual steps listed for collecting the information that a
>> pull request should contain, and no mention of having a proper
>> overall summary in the pull request that could be used for a
>> merge commit.
>>
>> There are other chunks of this file that need updates to match
>> current git workflows, but giant wholesale updates are more likely
>> to get caught up in bike shedding discussions over small details,
>> so lets start somewhere and attack the problem piece-wise.
>>
>> Signed-off-by: Paul Gortmaker <paul.gortmaker@windriver.com>
> 
> Did some "git <command>" create this patch?

git format-patch -p ....

> It is missing <quote>
>   - A marker line containing simply "---".
> </quote> just after the S-O-B line.

Not missing, just optional, and only required when you want to
temporarily pass on some transient information outside of the
commit log, such as diffstat, which I'd intentionally opted out
of here.

Paul.
--

> 
> 
>>
>> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
>> index 6e97e73..6102da9 100644
>> --- a/Documentation/SubmittingPatches
>> +++ b/Documentation/SubmittingPatches
>> @@ -590,33 +590,32 @@ See more details on the proper patch format in the following
>>  references.
>>  
>>  
>> -16) Sending "git pull" requests  (from Linus emails)
>> -
>> -Please write the git repo address and branch name alone on the same line
>> -so that I can't even by mistake pull from the wrong branch, and so
>> -that a triple-click just selects the whole thing.
>> -
>> -So the proper format is something along the lines of:
>> -
>> -	"Please pull from
>> -
>> -		git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus
>> -
>> -	 to get these changes:"
>> -
>> -so that I don't have to hunt-and-peck for the address and inevitably
>> -get it wrong (actually, I've only gotten it wrong a few times, and
>> -checking against the diffstat tells me when I get it wrong, but I'm
>> -just a lot more comfortable when I don't have to "look for" the right
>> -thing to pull, and double-check that I have the right branch-name).
>> -
>> -
>> -Please use "git diff -M --stat --summary" to generate the diffstat:
>> -the -M enables rename detection, and the summary enables a summary of
>> -new/deleted or renamed files.
>> -
>> -With rename detection, the statistics are rather different [...]
>> -because git will notice that a fair number of the changes are renames.
>> +16) Sending "git pull" requests
>> +
>> +For a long time now, the "git request-pull" command has existed,
>> +and gives a uniform pre-canned text with all the expected information
>> +within it.  Use this as the basis of your pull request e-mail, and
>> +prefix it with a sensible description of what the overall series
>> +of commits achieves.  Assume that this text will be used by the
>> +maintainer in their merge commit of your changes, and hence be part
>> +of the git history, just like the changelog of each commit.  Use
>> +the triple dash described above to separate the merge commit text
>> +in the top of your mail from the output from "git request-pull".
>> +
>> +You are strongly discouraged against manually creating your own
> 
>                     discouraged from
> (I would say, but no big deal.)
> 
>> +pull request text.  Doing so just increases the odds of having
>> +a typo in the repo location, the branch name, or other missing
>> +information.  In addition to creating all the required text output,
>> +the command also validates that your commits are actually reachable
>> +at the specified location, ensuring you don't waste the maintainer's
>> +time with having to hunt around trying find the location that you
>> +really meant.
>> +
>> +Your mail subject should be prefixed with "[GIT PULL]" and also
>> +mention the subsystem it is for, and if possible a very brief
>> +theme of what the changes achieve, e.g.
>> +
>> +   "[GIT PULL] x86: Remove uniprocessor support"
> 
> Lots of pull requests $Subject line also includes a kernel version number
> that the pull is for, e.g.,
> 
> [GIT pull] x86 updates for 3.11
> 
> I find that helpful in searching.  IOW, I would prefer to see that instead
> of 12 emails with the same subject of
> 
> [GIT pull] x86 updates
> 
> for kernel versions 3.0 thru 3.11.
> 
>>  
>>  -----------------------------------
>>  SECTION 2 - HINTS, TIPS, AND TRICKS
>>
> 
> 

Re: [PATCH] Documentation: update git pull info in SubmittingPatches

[Randy Dunlap]

On 07/15/13 14:40, Paul Gortmaker wrote:
> On 13-07-15 05:31 PM, Randy Dunlap wrote:
>> On 07/15/13 14:18, Paul Gortmaker wrote:
>>> The info in this section was overdue for an update; it had manual
>>> individual steps listed for collecting the information that a
>>> pull request should contain, and no mention of having a proper
>>> overall summary in the pull request that could be used for a
>>> merge commit.
>>>
>>> There are other chunks of this file that need updates to match
>>> current git workflows, but giant wholesale updates are more likely
>>> to get caught up in bike shedding discussions over small details,
>>> so lets start somewhere and attack the problem piece-wise.
>>>
>>> Signed-off-by: Paul Gortmaker <paul.gortmaker@windriver.com>
>>
>> Did some "git <command>" create this patch?
> 
> git format-patch -p ....
> 
>> It is missing <quote>
>>   - A marker line containing simply "---".
>> </quote> just after the S-O-B line.
> 
> Not missing, just optional, and only required when you want to
> temporarily pass on some transient information outside of the
> commit log, such as diffstat, which I'd intentionally opted out
> of here.

I didn't know that.
I guess that you can also fix that part of SubmittingPatches some day.

> 
> Paul.
> --
> 
>>
>>
>>>
>>> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
>>> index 6e97e73..6102da9 100644
>>> --- a/Documentation/SubmittingPatches
>>> +++ b/Documentation/SubmittingPatches
>>> @@ -590,33 +590,32 @@ See more details on the proper patch format in the following
>>>  references.
>>>  
>>>  
>>> -16) Sending "git pull" requests  (from Linus emails)
>>> -
>>> -Please write the git repo address and branch name alone on the same line
>>> -so that I can't even by mistake pull from the wrong branch, and so
>>> -that a triple-click just selects the whole thing.
>>> -
>>> -So the proper format is something along the lines of:
>>> -
>>> -	"Please pull from
>>> -
>>> -		git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus
>>> -
>>> -	 to get these changes:"
>>> -
>>> -so that I don't have to hunt-and-peck for the address and inevitably
>>> -get it wrong (actually, I've only gotten it wrong a few times, and
>>> -checking against the diffstat tells me when I get it wrong, but I'm
>>> -just a lot more comfortable when I don't have to "look for" the right
>>> -thing to pull, and double-check that I have the right branch-name).
>>> -
>>> -
>>> -Please use "git diff -M --stat --summary" to generate the diffstat:
>>> -the -M enables rename detection, and the summary enables a summary of
>>> -new/deleted or renamed files.
>>> -
>>> -With rename detection, the statistics are rather different [...]
>>> -because git will notice that a fair number of the changes are renames.
>>> +16) Sending "git pull" requests
>>> +
>>> +For a long time now, the "git request-pull" command has existed,
>>> +and gives a uniform pre-canned text with all the expected information
>>> +within it.  Use this as the basis of your pull request e-mail, and
>>> +prefix it with a sensible description of what the overall series
>>> +of commits achieves.  Assume that this text will be used by the
>>> +maintainer in their merge commit of your changes, and hence be part
>>> +of the git history, just like the changelog of each commit.  Use
>>> +the triple dash described above to separate the merge commit text
>>> +in the top of your mail from the output from "git request-pull".
>>> +
>>> +You are strongly discouraged against manually creating your own
>>
>>                     discouraged from
>> (I would say, but no big deal.)
>>
>>> +pull request text.  Doing so just increases the odds of having
>>> +a typo in the repo location, the branch name, or other missing
>>> +information.  In addition to creating all the required text output,
>>> +the command also validates that your commits are actually reachable
>>> +at the specified location, ensuring you don't waste the maintainer's
>>> +time with having to hunt around trying find the location that you
>>> +really meant.
>>> +
>>> +Your mail subject should be prefixed with "[GIT PULL]" and also
>>> +mention the subsystem it is for, and if possible a very brief
>>> +theme of what the changes achieve, e.g.
>>> +
>>> +   "[GIT PULL] x86: Remove uniprocessor support"
>>
>> Lots of pull requests $Subject line also includes a kernel version number
>> that the pull is for, e.g.,
>>
>> [GIT pull] x86 updates for 3.11
>>
>> I find that helpful in searching.  IOW, I would prefer to see that instead
>> of 12 emails with the same subject of
>>
>> [GIT pull] x86 updates
>>
>> for kernel versions 3.0 thru 3.11.
>>
>>>  
>>>  -----------------------------------
>>>  SECTION 2 - HINTS, TIPS, AND TRICKS
>>>
>>
>>


-- 
~Randy

Re: [PATCH] Documentation: update git pull info in SubmittingPatches

[H. Peter Anvin]

Something else to put in there: if someone absolutely feels the need to
put cover text before the patch, it should be separated from the patch
proper by a scissor line (---8<---) or there is no support for
automating the patch.

	-hpa

Re: [PATCH] Documentation: update git pull info in SubmittingPatches

[Paul Gortmaker]

On 13-07-15 05:57 PM, H. Peter Anvin wrote:
> Something else to put in there: if someone absolutely feels the need to
> put cover text before the patch, it should be separated from the patch
> proper by a scissor line (---8<---) or there is no support for
> automating the patch.

Sounds reasonable; I'll add it to my mental to-do list for sections
to update in this file.

Re: [PATCH] Documentation: update git pull info in SubmittingPatches

[Paul Gortmaker]

On 13-07-20 12:35 PM, Rob Landley wrote:
> On 07/15/2013 04:18:16 PM, Paul Gortmaker wrote:
>> The info in this section was overdue for an update; it had manual
>> individual steps listed for collecting the information that a
>> pull request should contain, and no mention of having a proper
>> overall summary in the pull request that could be used for a
>> merge commit.
>>
>> There are other chunks of this file that need updates to match
>> current git workflows, but giant wholesale updates are more likely
>> to get caught up in bike shedding discussions over small details,
>> so lets start somewhere and attack the problem piece-wise.
>>
>> Signed-off-by: Paul Gortmaker <paul.gortmaker@windriver.com>
> 
> Acked-by: Rob Landley <rob@landley.net>

Hi Rob,

I see you added trivial to the CC but (inadvertently?) dropped the
linux-doc (and lkml) from the CC.

Were you wanting this patch to go via the trivial tree?  Perhaps that
would be OK if there was just a one-off single doc patch, but even in
this case, it isn't really what I'd call trivial.  There is a genuine
change here -- we describe a new way of how to do pull requests, and
if someone doesn't like that change, they would be fair in complaining
about it "sneaking in" via the trivial tree.

I guess my point is that there are more doc patches coming; I've got
the one Jon acked, the Changes removal, and more in the works, so I'd
rather see these stacked in a real doc branch somewhere.  I don't think
it makes sense to vector all doc patches via trivial tree.

Didn't you recently get your kernel.org details sorted out for that, or
am I thinking of someone else?  In any case, if you aren't able to collect
them on a branch for one reason or another, I'll simply collect the acks
etc. myself and stack them up on a public branch on kernel.org.

Thanks,
Paul.
--

> 
>> diff --git a/Documentation/SubmittingPatches  
>> b/Documentation/SubmittingPatches
>> index 6e97e73..6102da9 100644
>> --- a/Documentation/SubmittingPatches
>> +++ b/Documentation/SubmittingPatches
>> @@ -590,33 +590,32 @@ See more details on the proper patch format in  
>> the following
>>  references.
>>
>>
>> -16) Sending "git pull" requests  (from Linus emails)
>> -
>> -Please write the git repo address and branch name alone on the same  
>> line
>> -so that I can't even by mistake pull from the wrong branch, and so
>> -that a triple-click just selects the whole thing.
>> -
>> -So the proper format is something along the lines of:
>> -
>> -	"Please pull from
>> -
>> -		git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus
>> -
>> -	 to get these changes:"
>> -
>> -so that I don't have to hunt-and-peck for the address and inevitably
>> -get it wrong (actually, I've only gotten it wrong a few times, and
>> -checking against the diffstat tells me when I get it wrong, but I'm
>> -just a lot more comfortable when I don't have to "look for" the right
>> -thing to pull, and double-check that I have the right branch-name).
>> -
>> -
>> -Please use "git diff -M --stat --summary" to generate the diffstat:
>> -the -M enables rename detection, and the summary enables a summary of
>> -new/deleted or renamed files.
>> -
>> -With rename detection, the statistics are rather different [...]
>> -because git will notice that a fair number of the changes are  
>> renames.
>> +16) Sending "git pull" requests
>> +
>> +For a long time now, the "git request-pull" command has existed,
>> +and gives a uniform pre-canned text with all the expected information
>> +within it.  Use this as the basis of your pull request e-mail, and
>> +prefix it with a sensible description of what the overall series
>> +of commits achieves.  Assume that this text will be used by the
>> +maintainer in their merge commit of your changes, and hence be part
>> +of the git history, just like the changelog of each commit.  Use
>> +the triple dash described above to separate the merge commit text
>> +in the top of your mail from the output from "git request-pull".
>> +
>> +You are strongly discouraged against manually creating your own
>> +pull request text.  Doing so just increases the odds of having
>> +a typo in the repo location, the branch name, or other missing
>> +information.  In addition to creating all the required text output,
>> +the command also validates that your commits are actually reachable
>> +at the specified location, ensuring you don't waste the maintainer's
>> +time with having to hunt around trying find the location that you
>> +really meant.
>> +
>> +Your mail subject should be prefixed with "[GIT PULL]" and also
>> +mention the subsystem it is for, and if possible a very brief
>> +theme of what the changes achieve, e.g.
>> +
>> +   "[GIT PULL] x86: Remove uniprocessor support"
>>
>>  -----------------------------------
>>  SECTION 2 - HINTS, TIPS, AND TRICKS
>> --
>> 1.8.1.2
>>
>>
>