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