Documentation/maintainer/pull-requests.rst

   1 .. _pullrequests:
   2
   3 Creating Pull Requests
   4 ======================
   5
   6 This chapter describes how maintainers can create and submit pull requests
   7 to other maintainers. This is useful for transferring changes from one
   8 maintainers tree to another maintainers tree.
   9
  10 This document was written by Tobin C. Harding (who at that time, was not an
  11 experienced maintainer) primarily from comments made by Greg Kroah-Hartman
  12 and Linus Torvalds on LKML. Suggestions and fixes by Jonathan Corbet and
  13 Mauro Carvalho Chehab.  Misrepresentation was unintentional but inevitable,
  14 please direct abuse to Tobin C. Harding <me@tobin.cc>.
  15
  16 Original email thread::
  17
  18         http://lkml.kernel.org/r/20171114110500.GA21175@kroah.com
  19
  20
  21 Create Branch
  22 -------------
  23
  24 To start with you will need to have all the changes you wish to include in
  25 the pull request on a separate branch. Typically you will base this branch
  26 off of a branch in the developers tree whom you intend to send the pull
  27 request to.
  28
  29 In order to create the pull request you must first tag the branch that you
  30 have just created. It is recommended that you choose a meaningful tag name,
  31 in a way that you and others can understand, even after some time.  A good
  32 practice is to include in the name an indicator of the sybsystem of origin
  33 and the target kernel version.
  34
  35 Greg offers the following. A pull request with miscellaneous stuff for
  36 drivers/char, to be applied at the Kernel version 4.15-rc1 could be named
  37 as ``char-misc-4.15-rc1``. If such tag would be produced from a branch
  38 named ``char-misc-next``, you would be using the following command::
  39
  40         git tag -s char-misc-4.15-rc1 char-misc-next
  41
  42 that will create a signed tag called ``char-misc-4.15-rc1`` based on the
  43 last commit in the ``char-misc-next`` branch, and sign it with your gpg key
  44 (see :ref:`Documentation/maintainer/configure-git.rst <configuregit>`).
  45
  46 Linus will only accept pull requests based on a signed tag. Other
  47 maintainers may differ.
  48
  49 When you run the above command ``git`` will drop you into an editor and ask
  50 you to describe the tag.  In this case, you are describing a pull request,
  51 so outline what is contained here, why it should be merged, and what, if
  52 any, testing has been done.  All of this information will end up in the tag
  53 itself, and then in the merge commit that the maintainer makes if/when they
  54 merge the pull request. So write it up well, as it will be in the kernel
  55 tree for forever.
  56
  57 As said by Linus::
  58
  59         Anyway, at least to me, the important part is the *message*. I want
  60         to understand what I'm pulling, and why I should pull it. I also
  61         want to use that message as the message for the merge, so it should
  62         not just make sense to me, but make sense as a historical record
  63         too.
  64
  65         Note that if there is something odd about the pull request, that
  66         should very much be in the explanation. If you're touching files
  67         that you don't maintain, explain _why_. I will see it in the
  68         diffstat anyway, and if you didn't mention it, I'll just be extra
  69         suspicious.  And when you send me new stuff after the merge window
  70         (or even bug-fixes, but ones that look scary), explain not just
  71         what they do and why they do it, but explain the _timing_. What
  72         happened that this didn't go through the merge window..
  73
  74         I will take both what you write in the email pull request _and_ in
  75         the signed tag, so depending on your workflow, you can either
  76         describe your work in the signed tag (which will also automatically
  77         make it into the pull request email), or you can make the signed
  78         tag just a placeholder with nothing interesting in it, and describe
  79         the work later when you actually send me the pull request.
  80
  81         And yes, I will edit the message. Partly because I tend to do just
  82         trivial formatting (the whole indentation and quoting etc), but
  83         partly because part of the message may make sense for me at pull
  84         time (describing the conflicts and your personal issues for sending
  85         it right now), but may not make sense in the context of a merge
  86         commit message, so I will try to make it all make sense. I will
  87         also fix any speeling mistaeks and bad grammar I notice,
  88         particularly for non-native speakers (but also for native ones
  89         ;^). But I may miss some, or even add some.
  90
  91                         Linus
  92
  93 Greg gives, as an example pull request::
  94
  95         Char/Misc patches for 4.15-rc1
  96
  97         Here is the big char/misc patch set for the 4.15-rc1 merge window.
  98         Contained in here is the normal set of new functions added to all
  99         of these crazy drivers, as well as the following brand new
 100         subsystems:
 101                 - time_travel_controller: Finally a set of drivers for the
 102                   latest time travel bus architecture that provides i/o to
 103                   the CPU before it asked for it, allowing uninterrupted
 104                   processing
 105                 - relativity_shifters: due to the affect that the
 106                   time_travel_controllers have on the overall system, there
 107                   was a need for a new set of relativity shifter drivers to
 108                   accommodate the newly formed black holes that would
 109                   threaten to suck CPUs into them.  This subsystem handles
 110                   this in a way to successfully neutralize the problems.
 111                   There is a Kconfig option to force these to be enabled
 112                   when needed, so problems should not occur.
 113
 114         All of these patches have been successfully tested in the latest
 115         linux-next releases, and the original problems that it found have
 116         all been resolved (apologies to anyone living near Canberra for the
 117         lack of the Kconfig options in the earlier versions of the
 118         linux-next tree creations.)
 119
 120         Signed-off-by: Your-name-here <your_email@domain>
 121
 122
 123 The tag message format is just like a git commit id.  One line at the top
 124 for a "summary subject" and be sure to sign-off at the bottom.
 125
 126 Now that you have a local signed tag, you need to push it up to where it
 127 can be retrieved::
 128
 129         git push origin char-misc-4.15-rc1
 130
 131
 132 Create Pull Request
 133 -------------------
 134
 135 The last thing to do is create the pull request message.  ``git`` handily
 136 will do this for you with the ``git request-pull`` command, but it needs a
 137 bit of help determining what you want to pull, and on what to base the pull
 138 against (to show the correct changes to be pulled and the diffstat). The
 139 following command(s) will generate a pull request::
 140
 141         git request-pull master git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/char-misc.git/ char-misc-4.15-rc1
 142
 143 Quoting Greg::
 144
 145         This is asking git to compare the difference from the
 146         'char-misc-4.15-rc1' tag location, to the head of the 'master'
 147         branch (which in my case points to the last location in Linus's
 148         tree that I diverged from, usually a -rc release) and to use the
 149         git:// protocol to pull from.  If you wish to use https://, that
 150         can be used here instead as well (but note that some people behind
 151         firewalls will have problems with https git pulls).
 152
 153         If the char-misc-4.15-rc1 tag is not present in the repo that I am
 154         asking to be pulled from, git will complain saying it is not there,
 155         a handy way to remember to actually push it to a public location.
 156
 157         The output of 'git request-pull' will contain the location of the
 158         git tree and specific tag to pull from, and the full text
 159         description of that tag (which is why you need to provide good
 160         information in that tag).  It will also create a diffstat of the
 161         pull request, and a shortlog of the individual commits that the
 162         pull request will provide.
 163
 164 Linus responded that he tends to prefer the ``git://`` protocol. Other
 165 maintainers may have different preferences. Also, note that if you are
 166 creating pull requests without a signed tag then ``https://`` may be a
 167 better choice. Please see the original thread for the full discussion.
 168
 169
 170 Submit Pull Request
 171 -------------------
 172
 173 A pull request is submitted in the same way as an ordinary patch. Send as
 174 inline email to the maintainer and CC LKML and any sub-system specific
 175 lists if required. Pull requests to Linus typically have a subject line
 176 something like::
 177
 178         [GIT PULL] <subsystem> changes for v4.15-rc1