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@xxxxxxxxxxxxx>
>>
>> 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
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/