Hi Greg, This is totally asking a favour, feel free to ignore. How do you format your [GIT PULL] emails to Linus? Do you create a tag and then run a git command to get the email? I tried to do it manually and failed pretty hard (as you no doubt will notice on LKML). thanks, Tobin.
Adding lkml and linux-doc mailing lists... On Tue, Nov 14, 2017 at 10:11:55AM +1100, Tobin C. Harding wrote:
Hi Greg,
This is totally asking a favour, feel free to ignore. How do you format your [GIT PULL] emails to Linus? Do you create a tag and then run a git command to get the email?
I tried to do it manually and failed pretty hard (as you no doubt will notice on LKML).
Well, I think you got it right the third time, so nice job :) Anyway, this actually came up at the kernel summit / maintainer meeting a few weeks ago, in that "how do I make a good pull request to Linus" is something we need to document. Here's what I do, and it seems to work well, so maybe we should turn it into the start of the documentation for how to do it. ----------- To start with, put your changes on a branch, hopefully one named in a semi-useful way (I use 'char-misc-next' for my char/misc driver patches to be merged into linux-next). That is the branch you wish to tag and have Linus pull from. Name the tag with something useful that you can understand if you run across it in a few weeks, and something that will be "unique". Continuing the example of my char-misc tree, for the patches to be sent to Linus for the 4.15-rc1 merge window, I would name the tag 'char-misc-4.15-rc1': git tag -u KEY_ID -s char-misc-4.15-rc1 char-misc-next that will create a signed tag called 'char-misc-4.15-rc1' based on the last commit in the char-misc-next branch, and sign it with my gpg key KEY_ID (replace KEY_ID with your own gpg key id.) When you run the above command, git will drop you into an editor and ask you to describe the tag. In this case, you are describing a pull request, so outline what is contained here, why it should be merged, and what, if any, testing has happened to it. All of this information will end up in the tag itself, and then in the merge commit that Linus makes, so write it up well, as it will be in the kernel tree for forever. An example pull request of mine might look like: Char/Misc patches for 4.15-rc1 Here is the big char/misc patch set for the 4.15-rc1 merge window. Contained in here is the normal set of new functions added to all of these crazy drivers, as well as the following brand new subsystems: - time_travel_controller: Finally a set of drivers for the latest time travel bus architecture that provides i/o to the CPU before it asked for it, allowing uninterrupted processing - relativity_shifters: due to the affect that the time_travel_controllers have on the overall system, there was a need for a new set of relativity shifter drivers to accommodate the newly formed black holes that would threaten to suck CPUs into them. This subsystem handles this in a way to successfully neutralize the problems. There is a Kconfig option to force these to be enabled when needed, so problems should not occur. All of these patches have been successfully tested in the latest linux-next releases, and the original problems that it found have all been resolved (apologies to anyone living near Canberra for the lack of the Kconfig options in the earlier versions of the linux-next tree creations.) Signed-off-by: Your-name-here <your_email@domain> The tag message format is just like a git commit id. One line at the top for a "summary subject" and be sure to sign-off at the bottom. Now that you have a local signed tag, you need to push it up to where it can be retrieved by others: git push origin char-misc-4.15-rc1 pushes the char-misc-4.15-rc1 tag to where the 'origin' repo is located. The last thing to do is create the pull request message. Git handily will do this for you with the 'git request-pull' command, but it needs a bit of help determining what you want to pull, and what to base the pull against (to show the correct changes to be pulled and the diffstat.) I use the following command to generate a pull request: git request-pull master git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/char-misc.git/ char-misc-4.15-rc1 This is asking git to compare the difference from the 'char-misc-4.15-rc1' tag location, to the head of the 'master' branch (which in my case points to the last location in Linus's tree that I diverged from, usually a -rc release) and to use the git:// protocol to pull from. If you wish to use https://, that can be used here instead as well (but note that some people behind firewalls will have problems with https git pulls). If the char-misc-4.15-rc1 tag is not present in the repo that I am asking to be pulled from, git will complain saying it is not there, a handy way to remember to actually push it to a public location. The output of 'git request-pull' will contain the location of the git tree and specific tag to pull from, and the full text description of that tag (which is why you need to provide good information in that tag.) It will also create a diffstat of the pull request, and a shortlog of the individual commits that the pull request will provide. ----------- Does all of that make sense? Anything I can explain better? It's just 3 commands to do to create the tag, push it out, and create a pull request text to put in an email. I have a simple script that I use for this task to output to my console these 3 commands, based on what kernel tree I am currently in, and what branch I am on. You can find that script at: https://github.com/gregkh/gregkh-linux/blob/master/work/pull_request if you wish to laugh at my horrid perl skills :) Hope this helps, greg k-h
[...]
An example pull request of mine might look like: Char/Misc patches for 4.15-rc1
Here is the big char/misc patch set for the 4.15-rc1 merge window. Contained in here is the normal set of new functions added to all of these crazy drivers, as well as the following brand new subsystems: - time_travel_controller: Finally a set of drivers for the latest time travel bus architecture that provides i/o to the CPU before it asked for it, allowing uninterrupted processing - relativity_shifters: due to the affect that the time_travel_controllers have on the overall system, there was a need for a new set of relativity shifter drivers to accommodate the newly formed black holes that would threaten to suck CPUs into them. This subsystem handles this in a way to successfully neutralize the problems. There is a Kconfig option to force these to be enabled when needed, so problems should not occur.
All of these patches have been successfully tested in the latest linux-next releases, and the original problems that it found have all been resolved (apologies to anyone living near Canberra for the lack of the Kconfig options in the earlier versions of the linux-next tree creations.)
Signed-off-by: Your-name-here <your_email@domain>
The tag message format is just like a git commit id. One line at the top for a "summary subject" and be sure to sign-off at the bottom.
I don't add my s-o-b to signed tags for pull requests, but perhaps I should. However, I think most maintainers don't use it, and neither does it seems like Linus is preserving the tag when he does the pull. [...] Kind regards Uffe
On Tue, Nov 14, 2017 at 3:05 AM, Greg Kroah-Hartman <gregkh@linuxfoundation.org> wrote:
Name the tag with something useful that you can understand if you run across it in a few weeks, and something that will be "unique". Continuing the example of my char-misc tree, for the patches to be sent to Linus for the 4.15-rc1 merge window, I would name the tag 'char-misc-4.15-rc1': git tag -u KEY_ID -s char-misc-4.15-rc1 char-misc-next
Side note: since you _usually_ would use the same key for the same project, just set it once with git config user.signingkey "keyname" and if you use the same key for everything, just add "--global". Or just edit your .git/config or ~/.gitconfig file by hand, it's designed to be human-readable and writable, and not some garbage like XML: [torvalds@i7 ~]$ head -4 .gitconfig [user] name = Linus Torvalds email = torvalds@linux-foundation.org signingkey = torvalds@linux-foundation.org it's not really all that complicated ;) Then you don't need that "-u KEY_ID" when you sign things. Anyway, at least to me, the important part is the *message*. I want to understand what I'm pulling, and why I should pull it. I also want to use that message as the message for the merge, so it should not just make sense to me, but make sense as a historical record too. Note that if there is something odd about the pull request, that should very much be in the explanation. If you're touching files that you don't maintain, explain _why_. I will see it in the diffstat anyway, and if you didn't mention it, I'll just be extra suspicious. And when you send me new stuff after the merge window (or even bug-fixes, but ones that look scary), explain not just what they do and why they do it, but explain the _timing_. What happened that this didn't go through the merge window.. I will take both what you write in the email pull request _and_ in the signed tag, so depending on your workflow, you can either describe your work in the signed tag (which will also automatically make it into the pull request email), or you can make the signed tag just a placeholder with nothing interesting in it, and describe the work later when you actually send me the pull request. And yes, I will edit the message. Partly because I tend to do just trivial formatting (the whole indentation and quoting etc), but partly because part of the message may make sense for me at pull time (describing the conflicts and your personal issues for sending it right now), but may not make sense in the context of a merge commit message, so I will try to make it all make sense. I will also fix any speeling mistaeks and bad grammar I notice, particularly for non-native speakers (but also for native ones ;^). But I may miss some, or even add some. Linus
Added Linus to To: header. On Tue, Nov 14, 2017 at 12:05:00PM +0100, Greg Kroah-Hartman wrote:
Adding lkml and linux-doc mailing lists...
On Tue, Nov 14, 2017 at 10:11:55AM +1100, Tobin C. Harding wrote:
Hi Greg,
This is totally asking a favour, feel free to ignore. How do you format your [GIT PULL] emails to Linus? Do you create a tag and then run a git command to get the email?
I tried to do it manually and failed pretty hard (as you no doubt will notice on LKML).
Well, I think you got it right the third time, so nice job :)
Anyway, this actually came up at the kernel summit / maintainer meeting a few weeks ago, in that "how do I make a good pull request to Linus" is something we need to document.
Here's what I do, and it seems to work well, so maybe we should turn it into the start of the documentation for how to do it.
-----------
To start with, put your changes on a branch, hopefully one named in a semi-useful way (I use 'char-misc-next' for my char/misc driver patches to be merged into linux-next). That is the branch you wish to tag and have Linus pull from.
Name the tag with something useful that you can understand if you run across it in a few weeks, and something that will be "unique". Continuing the example of my char-misc tree, for the patches to be sent to Linus for the 4.15-rc1 merge window, I would name the tag 'char-misc-4.15-rc1': git tag -u KEY_ID -s char-misc-4.15-rc1 char-misc-next
that will create a signed tag called 'char-misc-4.15-rc1' based on the last commit in the char-misc-next branch, and sign it with my gpg key KEY_ID (replace KEY_ID with your own gpg key id.)
When you run the above command, git will drop you into an editor and ask you to describe the tag. In this case, you are describing a pull request, so outline what is contained here, why it should be merged, and what, if any, testing has happened to it. All of this information will end up in the tag itself, and then in the merge commit that Linus makes, so write it up well, as it will be in the kernel tree for forever.
An example pull request of mine might look like: Char/Misc patches for 4.15-rc1
Here is the big char/misc patch set for the 4.15-rc1 merge window. Contained in here is the normal set of new functions added to all of these crazy drivers, as well as the following brand new subsystems: - time_travel_controller: Finally a set of drivers for the latest time travel bus architecture that provides i/o to the CPU before it asked for it, allowing uninterrupted processing - relativity_shifters: due to the affect that the time_travel_controllers have on the overall system, there was a need for a new set of relativity shifter drivers to accommodate the newly formed black holes that would threaten to suck CPUs into them. This subsystem handles this in a way to successfully neutralize the problems. There is a Kconfig option to force these to be enabled when needed, so problems should not occur.
All of these patches have been successfully tested in the latest linux-next releases, and the original problems that it found have all been resolved (apologies to anyone living near Canberra for the lack of the Kconfig options in the earlier versions of the linux-next tree creations.)
Signed-off-by: Your-name-here <your_email@domain>
The tag message format is just like a git commit id. One line at the top for a "summary subject" and be sure to sign-off at the bottom.
Now that you have a local signed tag, you need to push it up to where it can be retrieved by others: git push origin char-misc-4.15-rc1 pushes the char-misc-4.15-rc1 tag to where the 'origin' repo is located.
The last thing to do is create the pull request message. Git handily will do this for you with the 'git request-pull' command, but it needs a bit of help determining what you want to pull, and what to base the pull against (to show the correct changes to be pulled and the diffstat.)
I use the following command to generate a pull request: git request-pull master git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/char-misc.git/ char-misc-4.15-rc1
This is asking git to compare the difference from the 'char-misc-4.15-rc1' tag location, to the head of the 'master' branch (which in my case points to the last location in Linus's tree that I diverged from, usually a -rc release) and to use the git:// protocol to pull from. If you wish to use https://, that can be used here instead as well (but note that some people behind firewalls will have problems with https git pulls).
Linus do you care what protocol? I'm patching Documentation and since the point is creating pull requests for you 'some people' don't matter. thanks, Tobin.
On Tue, Nov 14, 2017 at 1:33 PM, Tobin C. Harding <me@tobin.cc> wrote:
Linus do you care what protocol? I'm patching Documentation and since the point is creating pull requests for you 'some people' don't matter.
I actually tend to prefer the regular git:// protocol and signed tags. It's true that https should have the proper certificate and perhaps help with DNS spoofing, but I'm not convinced that git won't just accept self-signed random certs, and I basically don't think we should trust that. In contrast, using ssh I would actually trust, but it's not convenient and involves people sending things that aren't necessarily publicly available. So instead, I prefer just using git:// and not trying to fool people into thinking the protocol is secure - the security should come from the signed tag. And then people can do this: [url "ssh://git@gitolite.kernel.org"] insteadOf = https://git.kernel.org insteadOf = http://git.kernel.org insteadOf = git://git.kernel.org which makes git.kernel.org addresses use ssh, and avoid the whole possible DNS spoofing problem. That said, I actually would prefer even kernel.org repositories to just send pull requests with signed tags, despite the protocol itself being secure for that (and only that). Other hosts I will simply not trust without it because I can't do the above. Side note: there's an unrelated advantage of using "git://" over "https://". It means that people who do automation see that it's a git repo. It also means, for example, that people that highlight https:// URL's and perhaps use them for spam marking hopefully don't do that with git:// format. Linus
Linus Torvalds <torvalds@linux-foundation.org> writes:
On Tue, Nov 14, 2017 at 1:33 PM, Tobin C. Harding <me@tobin.cc> wrote:
Linus do you care what protocol? I'm patching Documentation and since the point is creating pull requests for you 'some people' don't matter.
I actually tend to prefer the regular git:// protocol and signed tags.
It's true that https should have the proper certificate and perhaps help with DNS spoofing, but I'm not convinced that git won't just accept self-signed random certs, and I basically don't think we should trust that.
git does not accept self-signed certs by default, at least in recent versions. Though you can do a trust-on-first-use type thing, by downloading the cert and telling git where to find it. So https does provide additional security vs git:// IMHO. There is some verification of the server and your data is encrypted on the wire. It's not like it would be trivial to MITM a git fetch to insert a malicious Makefile change, but it's also not *hard*.
In contrast, using ssh I would actually trust, but it's not convenient and involves people sending things that aren't necessarily publicly available.
So instead, I prefer just using git:// and not trying to fool people into thinking the protocol is secure - the security should come from the signed tag.
That's true, but only when you're pulling a signed tag, which for most people is not the common case. ...
That said, I actually would prefer even kernel.org repositories to just send pull requests with signed tags, despite the protocol itself being secure for that (and only that).
Which you mention here. cheers
On Tue, Nov 14, 2017 at 1:46 PM, Linus Torvalds <torvalds@linux-foundation.org> wrote:
And then people can do this:
[url "ssh://git@gitolite.kernel.org"] insteadOf = https://git.kernel.org insteadOf = http://git.kernel.org insteadOf = git://git.kernel.org
which makes git.kernel.org addresses use ssh, and avoid the whole possible DNS spoofing problem.
So credit goes for Konstantin for pointing that out, and I actually used it this merge window. A few notes for other people who end up doing this: (a) ssh is slower, and the gitolite machine is not as reachable. (b) it affects your merge commit message. As to (a), yes it's noticeable, but the extra couple of seconds isn't really that big of a deal. Depending on exactly where you are, though, you might end up wanting to use https:// to the public servers instead. But (b) actually ends up being annoying, because I don't like my merge commits to contain references to repositories that aren't actually available unless you have a kernel.org account. I tried to edit things up by hand, but honestly, that just meant that I forgot about 50% of the time. Do a git log --author=Torvalds --grep=ssh://gitolite to see my shameful lack of actually fixing up the end result. Happily, once you realize that you have the attention span of a slightly retarded chipmunk, and that you keep on forgetting to fix things up, you hopefully also go "I'm a moron, but I can compensate for that automatically". Which is simple. Just create a .git/hooks/prepare-commit-msg file that contains #!/bin/sh sed -i 's|ssh://gitolite.kernel.org/|git://git.kernel.org/|g' "$1" and make it executable, and git will do that commit message editing for you. Tadaa! Now you don't look like quite the tool that I did. Linus
On Tue, Nov 14, 2017 at 12:05:00PM +0100, Greg Kroah-Hartman wrote:
Adding lkml and linux-doc mailing lists...
On Tue, Nov 14, 2017 at 10:11:55AM +1100, Tobin C. Harding wrote:
Hi Greg,
This is totally asking a favour, feel free to ignore. How do you format your [GIT PULL] emails to Linus? Do you create a tag and then run a git command to get the email?
I tried to do it manually and failed pretty hard (as you no doubt will notice on LKML).
Well, I think you got it right the third time, so nice job :)
Lucky. Three strikes and your out isn't it?
Anyway, this actually came up at the kernel summit / maintainer meeting a few weeks ago, in that "how do I make a good pull request to Linus" is something we need to document.
Here's what I do, and it seems to work well, so maybe we should turn it into the start of the documentation for how to do it.
Patch to come.
-----------
To start with, put your changes on a branch, hopefully one named in a semi-useful way (I use 'char-misc-next' for my char/misc driver patches to be merged into linux-next). That is the branch you wish to tag and have Linus pull from.
Name the tag with something useful that you can understand if you run across it in a few weeks, and something that will be "unique". Continuing the example of my char-misc tree, for the patches to be sent to Linus for the 4.15-rc1 merge window, I would name the tag 'char-misc-4.15-rc1': git tag -u KEY_ID -s char-misc-4.15-rc1 char-misc-next
that will create a signed tag called 'char-misc-4.15-rc1' based on the last commit in the char-misc-next branch, and sign it with my gpg key KEY_ID (replace KEY_ID with your own gpg key id.)
When you run the above command, git will drop you into an editor and ask you to describe the tag. In this case, you are describing a pull request, so outline what is contained here, why it should be merged, and what, if any, testing has happened to it. All of this information will end up in the tag itself, and then in the merge commit that Linus makes, so write it up well, as it will be in the kernel tree for forever.
An example pull request of mine might look like: Char/Misc patches for 4.15-rc1
Here is the big char/misc patch set for the 4.15-rc1 merge window. Contained in here is the normal set of new functions added to all of these crazy drivers, as well as the following brand new subsystems: - time_travel_controller: Finally a set of drivers for the latest time travel bus architecture that provides i/o to the CPU before it asked for it, allowing uninterrupted processing - relativity_shifters: due to the affect that the time_travel_controllers have on the overall system, there was a need for a new set of relativity shifter drivers to accommodate the newly formed black holes that would threaten to suck CPUs into them. This subsystem handles this in a way to successfully neutralize the problems. There is a Kconfig option to force these to be enabled when needed, so problems should not occur.
All of these patches have been successfully tested in the latest linux-next releases, and the original problems that it found have all been resolved (apologies to anyone living near Canberra for the lack of the Kconfig options in the earlier versions of the linux-next tree creations.)
Signed-off-by: Your-name-here <your_email@domain>
The tag message format is just like a git commit id. One line at the top for a "summary subject" and be sure to sign-off at the bottom.
Now that you have a local signed tag, you need to push it up to where it can be retrieved by others: git push origin char-misc-4.15-rc1 pushes the char-misc-4.15-rc1 tag to where the 'origin' repo is located.
The last thing to do is create the pull request message. Git handily will do this for you with the 'git request-pull' command, but it needs a bit of help determining what you want to pull, and what to base the pull against (to show the correct changes to be pulled and the diffstat.)
I use the following command to generate a pull request: git request-pull master git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/char-misc.git/ char-misc-4.15-rc1
This is asking git to compare the difference from the 'char-misc-4.15-rc1' tag location, to the head of the 'master' branch (which in my case points to the last location in Linus's tree that I diverged from, usually a -rc release) and to use the git:// protocol to pull from. If you wish to use https://, that can be used here instead as well (but note that some people behind firewalls will have problems with https git pulls).
If the char-misc-4.15-rc1 tag is not present in the repo that I am asking to be pulled from, git will complain saying it is not there, a handy way to remember to actually push it to a public location.
The output of 'git request-pull' will contain the location of the git tree and specific tag to pull from, and the full text description of that tag (which is why you need to provide good information in that tag.) It will also create a diffstat of the pull request, and a shortlog of the individual commits that the pull request will provide.
-----------
Does all of that make sense? Anything I can explain better?
Awesome explanation. +1 for the new subsystems ;) thanks, Tobin.
participants (5)
-
Greg Kroah-Hartman -
Linus Torvalds -
Michael Ellerman -
Tobin C. Harding -
Ulf Hansson