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