Documentation: update git pull info in SubmittingPatches
PATCH 1/1 Documentation: update git pull info in SubmittingPatches
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.
Documentation/SubmittingPatches +26 -27
@@ -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
Signature · 1 line
1.8.1.2
Randy Dunlap
reviewerQuoted 6 lines · 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.
Quoted 6 lines
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 <[email protected]>
Did some "git <command>" create this patch?
It is missing <quote>
- A marker line containing simply "---".
</quote> just after the S-O-B line.
Quoted 39 lines
Documentation/SubmittingPatches +3
-27@@ -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,
Documentation/SubmittingPatches See more details on the proper patch format in the following · line 605
Quoted 10 lines
Documentation/SubmittingPatches +10
-0+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.)
Documentation/SubmittingPatches See more details on the proper patch format in the following · line 618
Quoted 13 lines
Documentation/SubmittingPatches +13
-0+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.
Quoted 4 lines
Documentation/SubmittingPatches +0
-0----------------------------------- SECTION 2 - HINTS, TIPS, AND TRICKS
Signature · 1 line
~Randy
Quoted 7 lines · Randy Dunlap
Quoted 6 lines · 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.
Quoted 8 lines
Quoted 6 lines
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 <[email protected]>Did some "git <command>" create this patch?
git format-patch -p ....
Quoted 3 lines
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.
--
Quoted 87 lines
Quoted 41 lines
Documentation/SubmittingPatches +3
-27@@ -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,Documentation/SubmittingPatches See more details on the proper patch format in the following · line 605
Quoted 10 lines
Documentation/SubmittingPatches +10
-0+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 owndiscouraged from
(I would say, but no big deal.)Documentation/SubmittingPatches See more details on the proper patch format in the following · line 618
Quoted 13 lines
Documentation/SubmittingPatches +13
-0+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.
Quoted 4 lines
Documentation/SubmittingPatches +0
-0----------------------------------- SECTION 2 - HINTS, TIPS, AND TRICKS
Randy Dunlap
reviewerQuoted 19 lines · Paul Gortmaker
Quoted 7 lines · Randy Dunlap
Quoted 6 lines · 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.
Quoted 8 lines
Quoted 6 lines
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 <[email protected]>Did some "git <command>" create this patch?
git format-patch -p ....
Quoted 8 lines
Quoted 3 lines
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.
Quoted 91 lines
Paul.
--Quoted 87 lines
Quoted 41 lines
Documentation/SubmittingPatches +3
-27@@ -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,Documentation/SubmittingPatches See more details on the proper patch format in the following · line 605
Quoted 10 lines
Documentation/SubmittingPatches +10
-0+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 owndiscouraged from
(I would say, but no big deal.)Documentation/SubmittingPatches See more details on the proper patch format in the following · line 618
Quoted 13 lines
Documentation/SubmittingPatches +13
-0+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.
Quoted 4 lines
Documentation/SubmittingPatches +0
-0----------------------------------- SECTION 2 - HINTS, TIPS, AND TRICKS
Signature · 1 line
~Randy
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
Quoted 4 lines · 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.
Sounds reasonable; I'll add it to my mental to-do list for sections to update in this file.
A message that is not in the archive (sent off-list or not yet received): 1374338111.3719.21@driftwood
Quoted 7 lines · Rob Landley
Quoted 6 lines · 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.
Quoted 8 lines
Quoted 6 lines
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 <[email protected]>Acked-by Rob Landley <[email protected]>
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.
--
Quoted 74 lines
Quoted 73 lines
Documentation/SubmittingPatches +0
-0@@ -590,33 +590,32 @@ See more details on the proper patch format inthe following
references.-16) Sending "git pull" requests (from Linus emails)
Documentation/SubmittingPatches +0
-2- -Please write the git repo address and branch name alone on the sameline
Documentation/SubmittingPatches +0
-24-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 arerenames.
+16) Sending "git pull" requestsDocumentation/SubmittingPatches +25
-1+ +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