Commit | Line | Data |
---|---|---|
9727a014 TH |
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 |