]>
Commit | Line | Data |
---|---|---|
f7c9fe4b MCC |
1 | .. _development_posting: |
2 | ||
3 | Posting patches | |
4 | =============== | |
75b02146 JC |
5 | |
6 | Sooner or later, the time comes when your work is ready to be presented to | |
7 | the community for review and, eventually, inclusion into the mainline | |
8 | kernel. Unsurprisingly, the kernel development community has evolved a set | |
9 | of conventions and procedures which are used in the posting of patches; | |
10 | following them will make life much easier for everybody involved. This | |
11 | document will attempt to cover these expectations in reasonable detail; | |
f77af637 FV |
12 | more information can also be found in the files |
13 | :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`, | |
14 | :ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>` | |
15 | and :ref:`Documentation/process/submit-checklist.rst <submitchecklist>`. | |
75b02146 JC |
16 | |
17 | ||
f7c9fe4b MCC |
18 | When to post |
19 | ------------ | |
75b02146 JC |
20 | |
21 | There is a constant temptation to avoid posting patches before they are | |
22 | completely "ready." For simple patches, that is not a problem. If the | |
23 | work being done is complex, though, there is a lot to be gained by getting | |
24 | feedback from the community before the work is complete. So you should | |
25 | consider posting in-progress work, or even making a git tree available so | |
26 | that interested developers can catch up with your work at any time. | |
27 | ||
28 | When posting code which is not yet considered ready for inclusion, it is a | |
29 | good idea to say so in the posting itself. Also mention any major work | |
30 | which remains to be done and any known problems. Fewer people will look at | |
31 | patches which are known to be half-baked, but those who do will come in | |
32 | with the idea that they can help you drive the work in the right direction. | |
33 | ||
34 | ||
f7c9fe4b MCC |
35 | Before creating patches |
36 | ----------------------- | |
75b02146 JC |
37 | |
38 | There are a number of things which should be done before you consider | |
39 | sending patches to the development community. These include: | |
40 | ||
41 | - Test the code to the extent that you can. Make use of the kernel's | |
42 | debugging tools, ensure that the kernel will build with all reasonable | |
43 | combinations of configuration options, use cross-compilers to build for | |
44 | different architectures, etc. | |
45 | ||
46 | - Make sure your code is compliant with the kernel coding style | |
47 | guidelines. | |
48 | ||
49 | - Does your change have performance implications? If so, you should run | |
50 | benchmarks showing what the impact (or benefit) of your change is; a | |
51 | summary of the results should be included with the patch. | |
52 | ||
53 | - Be sure that you have the right to post the code. If this work was done | |
54 | for an employer, the employer likely has a right to the work and must be | |
55 | agreeable with its release under the GPL. | |
56 | ||
57 | As a general rule, putting in some extra thought before posting code almost | |
58 | always pays back the effort in short order. | |
59 | ||
60 | ||
f7c9fe4b MCC |
61 | Patch preparation |
62 | ----------------- | |
75b02146 JC |
63 | |
64 | The preparation of patches for posting can be a surprising amount of work, | |
65 | but, once again, attempting to save time here is not generally advisable | |
66 | even in the short term. | |
67 | ||
68 | Patches must be prepared against a specific version of the kernel. As a | |
69 | general rule, a patch should be based on the current mainline as found in | |
5c050fb9 JC |
70 | Linus's git tree. When basing on mainline, start with a well-known release |
71 | point - a stable or -rc release - rather than branching off the mainline at | |
72 | an arbitrary spot. | |
73 | ||
74 | It may become necessary to make versions against -mm, linux-next, or a | |
75 | subsystem tree, though, to facilitate wider testing and review. Depending | |
76 | on the area of your patch and what is going on elsewhere, basing a patch | |
77 | against these other trees can require a significant amount of work | |
78 | resolving conflicts and dealing with API changes. | |
75b02146 JC |
79 | |
80 | Only the most simple changes should be formatted as a single patch; | |
81 | everything else should be made as a logical series of changes. Splitting | |
82 | up patches is a bit of an art; some developers spend a long time figuring | |
83 | out how to do it in the way that the community expects. There are a few | |
84 | rules of thumb, however, which can help considerably: | |
85 | ||
86 | - The patch series you post will almost certainly not be the series of | |
87 | changes found in your working revision control system. Instead, the | |
88 | changes you have made need to be considered in their final form, then | |
89 | split apart in ways which make sense. The developers are interested in | |
90 | discrete, self-contained changes, not the path you took to get to those | |
91 | changes. | |
92 | ||
93 | - Each logically independent change should be formatted as a separate | |
94 | patch. These changes can be small ("add a field to this structure") or | |
95 | large (adding a significant new driver, for example), but they should be | |
96 | conceptually small and amenable to a one-line description. Each patch | |
97 | should make a specific change which can be reviewed on its own and | |
98 | verified to do what it says it does. | |
99 | ||
100 | - As a way of restating the guideline above: do not mix different types of | |
101 | changes in the same patch. If a single patch fixes a critical security | |
102 | bug, rearranges a few structures, and reformats the code, there is a | |
103 | good chance that it will be passed over and the important fix will be | |
104 | lost. | |
105 | ||
106 | - Each patch should yield a kernel which builds and runs properly; if your | |
107 | patch series is interrupted in the middle, the result should still be a | |
108 | working kernel. Partial application of a patch series is a common | |
109 | scenario when the "git bisect" tool is used to find regressions; if the | |
110 | result is a broken kernel, you will make life harder for developers and | |
111 | users who are engaging in the noble work of tracking down problems. | |
112 | ||
5c050fb9 | 113 | - Do not overdo it, though. One developer once posted a set of edits |
75b02146 JC |
114 | to a single file as 500 separate patches - an act which did not make him |
115 | the most popular person on the kernel mailing list. A single patch can | |
116 | be reasonably large as long as it still contains a single *logical* | |
5c050fb9 | 117 | change. |
75b02146 JC |
118 | |
119 | - It can be tempting to add a whole new infrastructure with a series of | |
120 | patches, but to leave that infrastructure unused until the final patch | |
121 | in the series enables the whole thing. This temptation should be | |
122 | avoided if possible; if that series adds regressions, bisection will | |
123 | finger the last patch as the one which caused the problem, even though | |
124 | the real bug is elsewhere. Whenever possible, a patch which adds new | |
125 | code should make that code active immediately. | |
126 | ||
127 | Working to create the perfect patch series can be a frustrating process | |
128 | which takes quite a bit of time and thought after the "real work" has been | |
129 | done. When done properly, though, it is time well spent. | |
130 | ||
131 | ||
f7c9fe4b MCC |
132 | Patch formatting and changelogs |
133 | ------------------------------- | |
75b02146 JC |
134 | |
135 | So now you have a perfect series of patches for posting, but the work is | |
136 | not done quite yet. Each patch needs to be formatted into a message which | |
137 | quickly and clearly communicates its purpose to the rest of the world. To | |
138 | that end, each patch will be composed of the following: | |
139 | ||
140 | - An optional "From" line naming the author of the patch. This line is | |
141 | only necessary if you are passing on somebody else's patch via email, | |
142 | but it never hurts to add it when in doubt. | |
143 | ||
144 | - A one-line description of what the patch does. This message should be | |
145 | enough for a reader who sees it with no other context to figure out the | |
146 | scope of the patch; it is the line that will show up in the "short form" | |
147 | changelogs. This message is usually formatted with the relevant | |
148 | subsystem name first, followed by the purpose of the patch. For | |
149 | example: | |
150 | ||
f7c9fe4b MCC |
151 | :: |
152 | ||
75b02146 JC |
153 | gpio: fix build on CONFIG_GPIO_SYSFS=n |
154 | ||
155 | - A blank line followed by a detailed description of the contents of the | |
156 | patch. This description can be as long as is required; it should say | |
157 | what the patch does and why it should be applied to the kernel. | |
158 | ||
159 | - One or more tag lines, with, at a minimum, one Signed-off-by: line from | |
160 | the author of the patch. Tags will be described in more detail below. | |
161 | ||
5d98932a JC |
162 | The items above, together, form the changelog for the patch. Writing good |
163 | changelogs is a crucial but often-neglected art; it's worth spending | |
164 | another moment discussing this issue. When writing a changelog, you should | |
165 | bear in mind that a number of different people will be reading your words. | |
166 | These include subsystem maintainers and reviewers who need to decide | |
167 | whether the patch should be included, distributors and other maintainers | |
168 | trying to decide whether a patch should be backported to other kernels, bug | |
169 | hunters wondering whether the patch is responsible for a problem they are | |
170 | chasing, users who want to know how the kernel has changed, and more. A | |
171 | good changelog conveys the needed information to all of these people in the | |
172 | most direct and concise way possible. | |
173 | ||
174 | To that end, the summary line should describe the effects of and motivation | |
175 | for the change as well as possible given the one-line constraint. The | |
176 | detailed description can then amplify on those topics and provide any | |
177 | needed additional information. If the patch fixes a bug, cite the commit | |
5c050fb9 JC |
178 | which introduced the bug if possible (and please provide both the commit ID |
179 | and the title when citing commits). If a problem is associated with | |
5d98932a JC |
180 | specific log or compiler output, include that output to help others |
181 | searching for a solution to the same problem. If the change is meant to | |
182 | support other changes coming in later patch, say so. If internal APIs are | |
183 | changed, detail those changes and how other developers should respond. In | |
184 | general, the more you can put yourself into the shoes of everybody who will | |
185 | be reading your changelog, the better that changelog (and the kernel as a | |
186 | whole) will be. | |
187 | ||
188 | Needless to say, the changelog should be the text used when committing the | |
189 | change to a revision control system. It will be followed by: | |
75b02146 JC |
190 | |
191 | - The patch itself, in the unified ("-u") patch format. Using the "-p" | |
192 | option to diff will associate function names with changes, making the | |
193 | resulting patch easier for others to read. | |
194 | ||
195 | You should avoid including changes to irrelevant files (those generated by | |
196 | the build process, for example, or editor backup files) in the patch. The | |
197 | file "dontdiff" in the Documentation directory can help in this regard; | |
198 | pass it to diff with the "-X" option. | |
199 | ||
200 | The tags mentioned above are used to describe how various developers have | |
201 | been associated with the development of this patch. They are described in | |
f77af637 FV |
202 | detail in |
203 | the :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` | |
204 | document; what follows here is a brief summary. Each of these lines has | |
205 | the format: | |
75b02146 | 206 | |
f7c9fe4b MCC |
207 | :: |
208 | ||
75b02146 JC |
209 | tag: Full Name <email address> optional-other-stuff |
210 | ||
211 | The tags in common use are: | |
212 | ||
213 | - Signed-off-by: this is a developer's certification that he or she has | |
214 | the right to submit the patch for inclusion into the kernel. It is an | |
215 | agreement to the Developer's Certificate of Origin, the full text of | |
f77af637 FV |
216 | which can be found in :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` |
217 | Code without a proper signoff cannot be merged into the mainline. | |
75b02146 | 218 | |
24a2bb90 SC |
219 | - Co-developed-by: states that the patch was co-created by several developers; |
220 | it is a used to give attribution to co-authors (in addition to the author | |
221 | attributed by the From: tag) when multiple people work on a single patch. | |
222 | Every Co-developed-by: must be immediately followed by a Signed-off-by: of | |
223 | the associated co-author. Details and examples can be found in | |
224 | :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`. | |
8ee25f6f | 225 | |
75b02146 JC |
226 | - Acked-by: indicates an agreement by another developer (often a |
227 | maintainer of the relevant code) that the patch is appropriate for | |
228 | inclusion into the kernel. | |
229 | ||
230 | - Tested-by: states that the named person has tested the patch and found | |
231 | it to work. | |
232 | ||
233 | - Reviewed-by: the named developer has reviewed the patch for correctness; | |
f77af637 | 234 | see the reviewer's statement in :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` |
f27e1d24 | 235 | for more detail. |
75b02146 JC |
236 | |
237 | - Reported-by: names a user who reported a problem which is fixed by this | |
238 | patch; this tag is used to give credit to the (often underappreciated) | |
239 | people who test our code and let us know when things do not work | |
240 | correctly. | |
241 | ||
242 | - Cc: the named person received a copy of the patch and had the | |
243 | opportunity to comment on it. | |
244 | ||
245 | Be careful in the addition of tags to your patches: only Cc: is appropriate | |
246 | for addition without the explicit permission of the person named. | |
247 | ||
248 | ||
f7c9fe4b MCC |
249 | Sending the patch |
250 | ----------------- | |
75b02146 JC |
251 | |
252 | Before you mail your patches, there are a couple of other things you should | |
253 | take care of: | |
254 | ||
255 | - Are you sure that your mailer will not corrupt the patches? Patches | |
256 | which have had gratuitous white-space changes or line wrapping performed | |
257 | by the mail client will not apply at the other end, and often will not | |
258 | be examined in any detail. If there is any doubt at all, mail the patch | |
5c050fb9 | 259 | to yourself and convince yourself that it shows up intact. |
75b02146 | 260 | |
f77af637 FV |
261 | :ref:`Documentation/process/email-clients.rst <email_clients>` has some |
262 | helpful hints on making specific mail clients work for sending patches. | |
75b02146 JC |
263 | |
264 | - Are you sure your patch is free of silly mistakes? You should always | |
265 | run patches through scripts/checkpatch.pl and address the complaints it | |
266 | comes up with. Please bear in mind that checkpatch.pl, while being the | |
267 | embodiment of a fair amount of thought about what kernel patches should | |
268 | look like, is not smarter than you. If fixing a checkpatch.pl complaint | |
269 | would make the code worse, don't do it. | |
270 | ||
271 | Patches should always be sent as plain text. Please do not send them as | |
272 | attachments; that makes it much harder for reviewers to quote sections of | |
273 | the patch in their replies. Instead, just put the patch directly into your | |
274 | message. | |
275 | ||
276 | When mailing patches, it is important to send copies to anybody who might | |
277 | be interested in it. Unlike some other projects, the kernel encourages | |
278 | people to err on the side of sending too many copies; don't assume that the | |
279 | relevant people will see your posting on the mailing lists. In particular, | |
280 | copies should go to: | |
281 | ||
282 | - The maintainer(s) of the affected subsystem(s). As described earlier, | |
283 | the MAINTAINERS file is the first place to look for these people. | |
284 | ||
285 | - Other developers who have been working in the same area - especially | |
286 | those who might be working there now. Using git to see who else has | |
287 | modified the files you are working on can be helpful. | |
288 | ||
289 | - If you are responding to a bug report or a feature request, copy the | |
290 | original poster as well. | |
291 | ||
292 | - Send a copy to the relevant mailing list, or, if nothing else applies, | |
293 | the linux-kernel list. | |
294 | ||
295 | - If you are fixing a bug, think about whether the fix should go into the | |
2eb7f204 JP |
296 | next stable update. If so, stable@vger.kernel.org should get a copy of |
297 | the patch. Also add a "Cc: stable@vger.kernel.org" to the tags within | |
298 | the patch itself; that will cause the stable team to get a notification | |
299 | when your fix goes into the mainline. | |
75b02146 JC |
300 | |
301 | When selecting recipients for a patch, it is good to have an idea of who | |
302 | you think will eventually accept the patch and get it merged. While it | |
303 | is possible to send patches directly to Linus Torvalds and have him merge | |
304 | them, things are not normally done that way. Linus is busy, and there are | |
305 | subsystem maintainers who watch over specific parts of the kernel. Usually | |
306 | you will be wanting that maintainer to merge your patches. If there is no | |
307 | obvious maintainer, Andrew Morton is often the patch target of last resort. | |
308 | ||
309 | Patches need good subject lines. The canonical format for a patch line is | |
310 | something like: | |
311 | ||
f7c9fe4b MCC |
312 | :: |
313 | ||
75b02146 JC |
314 | [PATCH nn/mm] subsys: one-line description of the patch |
315 | ||
316 | where "nn" is the ordinal number of the patch, "mm" is the total number of | |
317 | patches in the series, and "subsys" is the name of the affected subsystem. | |
5c050fb9 | 318 | Clearly, nn/mm can be omitted for a single, standalone patch. |
75b02146 JC |
319 | |
320 | If you have a significant series of patches, it is customary to send an | |
321 | introductory description as part zero. This convention is not universally | |
322 | followed though; if you use it, remember that information in the | |
323 | introduction does not make it into the kernel changelogs. So please ensure | |
324 | that the patches, themselves, have complete changelog information. | |
325 | ||
326 | In general, the second and following parts of a multi-part patch should be | |
327 | sent as a reply to the first part so that they all thread together at the | |
328 | receiving end. Tools like git and quilt have commands to mail out a set of | |
329 | patches with the proper threading. If you have a long series, though, and | |
5c050fb9 | 330 | are using git, please stay away from the --chain-reply-to option to avoid |
75b02146 | 331 | creating exceptionally deep nesting. |