Skip to contentSkip to conversation

Documentation: update git pull info in SubmittingPatches

PATCH In review Paul Gortmaker 3 participants 7 messages Jul 15, 2013 – Jul 23, 2013 1 message not in the archive Documentation

lore
Share & tools
lore
#0 lore raw

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
index 6e97e73..6102da9 100644
@@ -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
reviewer
#1 lore raw
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 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.

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
index 6e97e73..6102da9 100644
@@ -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
#2 lore raw
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.

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
index 6e97e73..6102da9 100644
@@ -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
 
reviewer
#3 lore raw
Quoted 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.

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
index 6e97e73..6102da9 100644
@@ -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
#4 lore raw

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

#5 lore raw
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

#7 lore raw
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.

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
index 6e97e73..6102da9 100644
@@ -590,33 +590,32 @@ See more details on the proper patch format in  

the 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 same  

line

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 are  

renames.
+16) Sending "git pull" requests

Documentation/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