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