git pull

[me@tobin.cc (Tobin C. Harding)]

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.