Commit | Line | Data |
---|---|---|
1da177e4 LT |
1 | |
2 | How to Get Your Change Into the Linux Kernel | |
3 | or | |
4 | Care And Operation Of Your Linus Torvalds | |
5 | ||
6 | ||
7 | ||
8 | For a person or company who wishes to submit a change to the Linux | |
9 | kernel, the process can sometimes be daunting if you're not familiar | |
10 | with "the system." This text is a collection of suggestions which | |
11 | can greatly increase the chances of your change being accepted. | |
12 | ||
bc7455fa RD |
13 | Read Documentation/SubmitChecklist for a list of items to check |
14 | before submitting code. If you are submitting a driver, also read | |
15 | Documentation/SubmittingDrivers. | |
1da177e4 | 16 | |
8e3072a2 JT |
17 | Many of these steps describe the default behavior of the git version |
18 | control system; if you use git to prepare your patches, you'll find much | |
19 | of the mechanical work done for you, though you'll still need to prepare | |
20 | and document a sensible set of patches. | |
1da177e4 LT |
21 | |
22 | -------------------------------------------- | |
23 | SECTION 1 - CREATING AND SENDING YOUR CHANGE | |
24 | -------------------------------------------- | |
25 | ||
26 | ||
27 | ||
28 | 1) "diff -up" | |
29 | ------------ | |
30 | ||
8e3072a2 JT |
31 | Use "diff -up" or "diff -uprN" to create patches. git generates patches |
32 | in this form by default; if you're using git, you can skip this section | |
33 | entirely. | |
1da177e4 LT |
34 | |
35 | All changes to the Linux kernel occur in the form of patches, as | |
36 | generated by diff(1). When creating your patch, make sure to create it | |
37 | in "unified diff" format, as supplied by the '-u' argument to diff(1). | |
38 | Also, please use the '-p' argument which shows which C function each | |
39 | change is in - that makes the resultant diff a lot easier to read. | |
40 | Patches should be based in the root kernel source directory, | |
41 | not in any lower subdirectory. | |
42 | ||
43 | To create a patch for a single file, it is often sufficient to do: | |
44 | ||
84da7c08 | 45 | SRCTREE= linux-2.6 |
1da177e4 LT |
46 | MYFILE= drivers/net/mydriver.c |
47 | ||
48 | cd $SRCTREE | |
49 | cp $MYFILE $MYFILE.orig | |
50 | vi $MYFILE # make your change | |
51 | cd .. | |
52 | diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch | |
53 | ||
54 | To create a patch for multiple files, you should unpack a "vanilla", | |
55 | or unmodified kernel source tree, and generate a diff against your | |
56 | own source tree. For example: | |
57 | ||
84da7c08 | 58 | MYSRC= /devel/linux-2.6 |
1da177e4 | 59 | |
84da7c08 RD |
60 | tar xvfz linux-2.6.12.tar.gz |
61 | mv linux-2.6.12 linux-2.6.12-vanilla | |
62 | diff -uprN -X linux-2.6.12-vanilla/Documentation/dontdiff \ | |
63 | linux-2.6.12-vanilla $MYSRC > /tmp/patch | |
1da177e4 LT |
64 | |
65 | "dontdiff" is a list of files which are generated by the kernel during | |
66 | the build process, and should be ignored in any diff(1)-generated | |
84da7c08 | 67 | patch. The "dontdiff" file is included in the kernel tree in |
755727b7 | 68 | 2.6.12 and later. |
1da177e4 LT |
69 | |
70 | Make sure your patch does not include any extra files which do not | |
71 | belong in a patch submission. Make sure to review your patch -after- | |
72 | generated it with diff(1), to ensure accuracy. | |
73 | ||
8e3072a2 JT |
74 | If your changes produce a lot of deltas, you need to split them into |
75 | individual patches which modify things in logical stages; see section | |
76 | #3. This will facilitate easier reviewing by other kernel developers, | |
77 | very important if you want your patch accepted. | |
1da177e4 | 78 | |
8e3072a2 JT |
79 | If you're using git, "git rebase -i" can help you with this process. If |
80 | you're not using git, quilt <http://savannah.nongnu.org/projects/quilt> | |
81 | is another popular alternative. | |
84da7c08 RD |
82 | |
83 | ||
1da177e4 LT |
84 | |
85 | 2) Describe your changes. | |
86 | ||
7b9828d4 JW |
87 | Describe your problem. Whether your patch is a one-line bug fix or |
88 | 5000 lines of a new feature, there must be an underlying problem that | |
89 | motivated you to do this work. Convince the reviewer that there is a | |
90 | problem worth fixing and that it makes sense for them to read past the | |
91 | first paragraph. | |
92 | ||
93 | Describe user-visible impact. Straight up crashes and lockups are | |
94 | pretty convincing, but not all bugs are that blatant. Even if the | |
95 | problem was spotted during code review, describe the impact you think | |
96 | it can have on users. Keep in mind that the majority of Linux | |
97 | installations run kernels from secondary stable trees or | |
98 | vendor/product-specific trees that cherry-pick only specific patches | |
99 | from upstream, so include anything that could help route your change | |
100 | downstream: provoking circumstances, excerpts from dmesg, crash | |
101 | descriptions, performance regressions, latency spikes, lockups, etc. | |
102 | ||
103 | Quantify optimizations and trade-offs. If you claim improvements in | |
104 | performance, memory consumption, stack footprint, or binary size, | |
105 | include numbers that back them up. But also describe non-obvious | |
106 | costs. Optimizations usually aren't free but trade-offs between CPU, | |
107 | memory, and readability; or, when it comes to heuristics, between | |
108 | different workloads. Describe the expected downsides of your | |
109 | optimization so that the reviewer can weigh costs against benefits. | |
110 | ||
111 | Once the problem is established, describe what you are actually doing | |
112 | about it in technical detail. It's important to describe the change | |
113 | in plain English for the reviewer to verify that the code is behaving | |
114 | as you intend it to. | |
1da177e4 | 115 | |
2ae19aca TT |
116 | The maintainer will thank you if you write your patch description in a |
117 | form which can be easily pulled into Linux's source code management | |
118 | system, git, as a "commit log". See #15, below. | |
119 | ||
7b9828d4 JW |
120 | Solve only one problem per patch. If your description starts to get |
121 | long, that's a sign that you probably need to split up your patch. | |
122 | See #3, next. | |
1da177e4 | 123 | |
d89b1945 RD |
124 | When you submit or resubmit a patch or patch series, include the |
125 | complete patch description and justification for it. Don't just | |
126 | say that this is version N of the patch (series). Don't expect the | |
127 | patch merger to refer back to earlier patch versions or referenced | |
128 | URLs to find the patch description and put that into the patch. | |
129 | I.e., the patch (series) and its description should be self-contained. | |
130 | This benefits both the patch merger(s) and reviewers. Some reviewers | |
131 | probably didn't even receive earlier versions of the patch. | |
132 | ||
74a475ac JT |
133 | Describe your changes in imperative mood, e.g. "make xyzzy do frotz" |
134 | instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy | |
135 | to do frotz", as if you are giving orders to the codebase to change | |
136 | its behaviour. | |
137 | ||
d89b1945 | 138 | If the patch fixes a logged bug entry, refer to that bug entry by |
9547c706 JT |
139 | number and URL. If the patch follows from a mailing list discussion, |
140 | give a URL to the mailing list archive; use the https://lkml.kernel.org/ | |
141 | redirector with a Message-Id, to ensure that the links cannot become | |
142 | stale. | |
143 | ||
144 | However, try to make your explanation understandable without external | |
145 | resources. In addition to giving a URL to a mailing list archive or | |
146 | bug, summarize the relevant points of the discussion that led to the | |
147 | patch as submitted. | |
1da177e4 | 148 | |
0af52703 GU |
149 | If you want to refer to a specific commit, don't just refer to the |
150 | SHA-1 ID of the commit. Please also include the oneline summary of | |
151 | the commit, to make it easier for reviewers to know what it is about. | |
152 | Example: | |
153 | ||
154 | Commit e21d2170f36602ae2708 ("video: remove unnecessary | |
155 | platform_set_drvdata()") removed the unnecessary | |
156 | platform_set_drvdata(), but left the variable "dev" unused, | |
157 | delete it. | |
158 | ||
8401aa1f JK |
159 | If your patch fixes a bug in a specific commit, e.g. you found an issue using |
160 | git-bisect, please use the 'Fixes:' tag with the first 12 characters of the | |
161 | SHA-1 ID, and the one line summary. | |
162 | Example: | |
163 | ||
164 | Fixes: e21d2170f366 ("video: remove unnecessary platform_set_drvdata()") | |
165 | ||
166 | The following git-config settings can be used to add a pretty format for | |
167 | outputting the above style in the git log or git show commands | |
168 | ||
169 | [core] | |
170 | abbrev = 12 | |
171 | [pretty] | |
172 | fixes = Fixes: %h (\"%s\") | |
1da177e4 LT |
173 | |
174 | 3) Separate your changes. | |
175 | ||
5b0ed2c6 | 176 | Separate _logical changes_ into a single patch file. |
1da177e4 LT |
177 | |
178 | For example, if your changes include both bug fixes and performance | |
179 | enhancements for a single driver, separate those changes into two | |
180 | or more patches. If your changes include an API update, and a new | |
181 | driver which uses that new API, separate those into two patches. | |
182 | ||
183 | On the other hand, if you make a single change to numerous files, | |
184 | group those changes into a single patch. Thus a single logical change | |
185 | is contained within a single patch. | |
186 | ||
187 | If one patch depends on another patch in order for a change to be | |
188 | complete, that is OK. Simply note "this patch depends on patch X" | |
189 | in your patch description. | |
190 | ||
5b0ed2c6 XVP |
191 | If you cannot condense your patch set into a smaller set of patches, |
192 | then only post say 15 or so at a time and wait for review and integration. | |
193 | ||
194 | ||
1da177e4 | 195 | |
0a920b5b AW |
196 | 4) Style check your changes. |
197 | ||
198 | Check your patch for basic style violations, details of which can be | |
199 | found in Documentation/CodingStyle. Failure to do so simply wastes | |
f56d35e7 | 200 | the reviewers time and will get your patch rejected, probably |
0a920b5b AW |
201 | without even being read. |
202 | ||
203 | At a minimum you should check your patches with the patch style | |
a570ab6f | 204 | checker prior to submission (scripts/checkpatch.pl). You should |
0a920b5b AW |
205 | be able to justify all violations that remain in your patch. |
206 | ||
207 | ||
208 | ||
209 | 5) Select e-mail destination. | |
1da177e4 LT |
210 | |
211 | Look through the MAINTAINERS file and the source code, and determine | |
212 | if your change applies to a specific subsystem of the kernel, with | |
e52d2e1f MM |
213 | an assigned maintainer. If so, e-mail that person. The script |
214 | scripts/get_maintainer.pl can be very useful at this step. | |
1da177e4 LT |
215 | |
216 | If no maintainer is listed, or the maintainer does not respond, send | |
217 | your patch to the primary Linux kernel developer's mailing list, | |
218 | linux-kernel@vger.kernel.org. Most kernel developers monitor this | |
219 | e-mail list, and can comment on your changes. | |
220 | ||
5b0ed2c6 XVP |
221 | |
222 | Do not send more than 15 patches at once to the vger mailing lists!!! | |
223 | ||
224 | ||
1da177e4 | 225 | Linus Torvalds is the final arbiter of all changes accepted into the |
99ddcc7e LT |
226 | Linux kernel. His e-mail address is <torvalds@linux-foundation.org>. |
227 | He gets a lot of e-mail, so typically you should do your best to -avoid- | |
228 | sending him e-mail. | |
1da177e4 LT |
229 | |
230 | Patches which are bug fixes, are "obvious" changes, or similarly | |
231 | require little discussion should be sent or CC'd to Linus. Patches | |
232 | which require discussion or do not have a clear advantage should | |
233 | usually be sent first to linux-kernel. Only after the patch is | |
234 | discussed should the patch then be submitted to Linus. | |
235 | ||
1da177e4 LT |
236 | |
237 | ||
0a920b5b | 238 | 6) Select your CC (e-mail carbon copy) list. |
1da177e4 LT |
239 | |
240 | Unless you have a reason NOT to do so, CC linux-kernel@vger.kernel.org. | |
241 | ||
242 | Other kernel developers besides Linus need to be aware of your change, | |
243 | so that they may comment on it and offer code review and suggestions. | |
244 | linux-kernel is the primary Linux kernel developer mailing list. | |
245 | Other mailing lists are available for specific subsystems, such as | |
246 | USB, framebuffer devices, the VFS, the SCSI subsystem, etc. See the | |
247 | MAINTAINERS file for a mailing list that relates specifically to | |
248 | your change. | |
249 | ||
5b0ed2c6 XVP |
250 | Majordomo lists of VGER.KERNEL.ORG at: |
251 | <http://vger.kernel.org/vger-lists.html> | |
252 | ||
1caf1f0f PJ |
253 | If changes affect userland-kernel interfaces, please send |
254 | the MAN-PAGES maintainer (as listed in the MAINTAINERS file) | |
255 | a man-pages patch, or at least a notification of the change, | |
256 | so that some information makes its way into the manual pages. | |
257 | ||
8103b5cc | 258 | Even if the maintainer did not respond in step #5, make sure to ALWAYS |
1da177e4 LT |
259 | copy the maintainer when you change their code. |
260 | ||
261 | For small patches you may want to CC the Trivial Patch Monkey | |
82d27b2b MH |
262 | trivial@kernel.org which collects "trivial" patches. Have a look |
263 | into the MAINTAINERS file for its current manager. | |
264 | Trivial patches must qualify for one of the following rules: | |
1da177e4 | 265 | Spelling fixes in documentation |
8e9cb8fd | 266 | Spelling fixes which could break grep(1) |
1da177e4 LT |
267 | Warning fixes (cluttering with useless warnings is bad) |
268 | Compilation fixes (only if they are actually correct) | |
269 | Runtime fixes (only if they actually fix things) | |
8e9cb8fd | 270 | Removing use of deprecated functions/macros (eg. check_region) |
1da177e4 LT |
271 | Contact detail and documentation fixes |
272 | Non-portable code replaced by portable code (even in arch-specific, | |
273 | since people copy, as long as it's trivial) | |
8e9cb8fd | 274 | Any fix by the author/maintainer of the file (ie. patch monkey |
1da177e4 | 275 | in re-transmission mode) |
84da7c08 | 276 | |
1da177e4 LT |
277 | |
278 | ||
0a920b5b | 279 | 7) No MIME, no links, no compression, no attachments. Just plain text. |
1da177e4 LT |
280 | |
281 | Linus and other kernel developers need to be able to read and comment | |
282 | on the changes you are submitting. It is important for a kernel | |
283 | developer to be able to "quote" your changes, using standard e-mail | |
284 | tools, so that they may comment on specific portions of your code. | |
285 | ||
286 | For this reason, all patches should be submitting e-mail "inline". | |
287 | WARNING: Be wary of your editor's word-wrap corrupting your patch, | |
288 | if you choose to cut-n-paste your patch. | |
289 | ||
290 | Do not attach the patch as a MIME attachment, compressed or not. | |
291 | Many popular e-mail applications will not always transmit a MIME | |
292 | attachment as plain text, making it impossible to comment on your | |
293 | code. A MIME attachment also takes Linus a bit more time to process, | |
294 | decreasing the likelihood of your MIME-attached change being accepted. | |
295 | ||
296 | Exception: If your mailer is mangling patches then someone may ask | |
297 | you to re-send them using MIME. | |
298 | ||
097091c0 MO |
299 | See Documentation/email-clients.txt for hints about configuring |
300 | your e-mail client so that it sends your patches untouched. | |
1da177e4 | 301 | |
0a920b5b | 302 | 8) E-mail size. |
1da177e4 | 303 | |
0a920b5b | 304 | When sending patches to Linus, always follow step #7. |
1da177e4 LT |
305 | |
306 | Large changes are not appropriate for mailing lists, and some | |
4932be77 | 307 | maintainers. If your patch, uncompressed, exceeds 300 kB in size, |
1da177e4 LT |
308 | it is preferred that you store your patch on an Internet-accessible |
309 | server, and provide instead a URL (link) pointing to your patch. | |
310 | ||
311 | ||
312 | ||
0a920b5b | 313 | 9) Name your kernel version. |
1da177e4 LT |
314 | |
315 | It is important to note, either in the subject line or in the patch | |
316 | description, the kernel version to which this patch applies. | |
317 | ||
318 | If the patch does not apply cleanly to the latest kernel version, | |
319 | Linus will not apply it. | |
320 | ||
321 | ||
322 | ||
0a920b5b | 323 | 10) Don't get discouraged. Re-submit. |
1da177e4 LT |
324 | |
325 | After you have submitted your change, be patient and wait. If Linus | |
326 | likes your change and applies it, it will appear in the next version | |
327 | of the kernel that he releases. | |
328 | ||
329 | However, if your change doesn't appear in the next version of the | |
330 | kernel, there could be any number of reasons. It's YOUR job to | |
331 | narrow down those reasons, correct what was wrong, and submit your | |
332 | updated change. | |
333 | ||
334 | It is quite common for Linus to "drop" your patch without comment. | |
335 | That's the nature of the system. If he drops your patch, it could be | |
336 | due to | |
8e9cb8fd | 337 | * Your patch did not apply cleanly to the latest kernel version. |
1da177e4 | 338 | * Your patch was not sufficiently discussed on linux-kernel. |
8e9cb8fd PM |
339 | * A style issue (see section 2). |
340 | * An e-mail formatting issue (re-read this section). | |
341 | * A technical problem with your change. | |
342 | * He gets tons of e-mail, and yours got lost in the shuffle. | |
343 | * You are being annoying. | |
1da177e4 LT |
344 | |
345 | When in doubt, solicit comments on linux-kernel mailing list. | |
346 | ||
347 | ||
348 | ||
0a920b5b | 349 | 11) Include PATCH in the subject |
1da177e4 LT |
350 | |
351 | Due to high e-mail traffic to Linus, and to linux-kernel, it is common | |
352 | convention to prefix your subject line with [PATCH]. This lets Linus | |
353 | and other kernel developers more easily distinguish patches from other | |
354 | e-mail discussions. | |
355 | ||
356 | ||
357 | ||
0a920b5b | 358 | 12) Sign your work |
1da177e4 LT |
359 | |
360 | To improve tracking of who did what, especially with patches that can | |
361 | percolate to their final resting place in the kernel through several | |
362 | layers of maintainers, we've introduced a "sign-off" procedure on | |
363 | patches that are being emailed around. | |
364 | ||
365 | The sign-off is a simple line at the end of the explanation for the | |
366 | patch, which certifies that you wrote it or otherwise have the right to | |
db12fb83 | 367 | pass it on as an open-source patch. The rules are pretty simple: if you |
1da177e4 LT |
368 | can certify the below: |
369 | ||
cbd83da8 | 370 | Developer's Certificate of Origin 1.1 |
1da177e4 LT |
371 | |
372 | By making a contribution to this project, I certify that: | |
373 | ||
374 | (a) The contribution was created in whole or in part by me and I | |
375 | have the right to submit it under the open source license | |
376 | indicated in the file; or | |
377 | ||
378 | (b) The contribution is based upon previous work that, to the best | |
379 | of my knowledge, is covered under an appropriate open source | |
380 | license and I have the right under that license to submit that | |
381 | work with modifications, whether created in whole or in part | |
382 | by me, under the same open source license (unless I am | |
383 | permitted to submit under a different license), as indicated | |
384 | in the file; or | |
385 | ||
386 | (c) The contribution was provided directly to me by some other | |
387 | person who certified (a), (b) or (c) and I have not modified | |
388 | it. | |
389 | ||
cbd83da8 LT |
390 | (d) I understand and agree that this project and the contribution |
391 | are public and that a record of the contribution (including all | |
392 | personal information I submit with it, including my sign-off) is | |
393 | maintained indefinitely and may be redistributed consistent with | |
394 | this project or the open source license(s) involved. | |
395 | ||
1da177e4 LT |
396 | then you just add a line saying |
397 | ||
9fd5559c | 398 | Signed-off-by: Random J Developer <random@developer.example.org> |
1da177e4 | 399 | |
af45f32d GK |
400 | using your real name (sorry, no pseudonyms or anonymous contributions.) |
401 | ||
1da177e4 LT |
402 | Some people also put extra tags at the end. They'll just be ignored for |
403 | now, but you can do this to mark internal company procedures or just | |
404 | point out some special detail about the sign-off. | |
405 | ||
adbd5886 WT |
406 | If you are a subsystem or branch maintainer, sometimes you need to slightly |
407 | modify patches you receive in order to merge them, because the code is not | |
408 | exactly the same in your tree and the submitters'. If you stick strictly to | |
409 | rule (c), you should ask the submitter to rediff, but this is a totally | |
410 | counter-productive waste of time and energy. Rule (b) allows you to adjust | |
411 | the code, but then it is very impolite to change one submitter's code and | |
412 | make him endorse your bugs. To solve this problem, it is recommended that | |
413 | you add a line between the last Signed-off-by header and yours, indicating | |
414 | the nature of your changes. While there is nothing mandatory about this, it | |
415 | seems like prepending the description with your mail and/or name, all | |
416 | enclosed in square brackets, is noticeable enough to make it obvious that | |
417 | you are responsible for last-minute changes. Example : | |
418 | ||
419 | Signed-off-by: Random J Developer <random@developer.example.org> | |
420 | [lucky@maintainer.example.org: struct foo moved from foo.c to foo.h] | |
421 | Signed-off-by: Lucky K Maintainer <lucky@maintainer.example.org> | |
422 | ||
305af08c | 423 | This practice is particularly helpful if you maintain a stable branch and |
adbd5886 WT |
424 | want at the same time to credit the author, track changes, merge the fix, |
425 | and protect the submitter from complaints. Note that under no circumstances | |
426 | can you change the author's identity (the From header), as it is the one | |
427 | which appears in the changelog. | |
428 | ||
305af08c | 429 | Special note to back-porters: It seems to be a common and useful practice |
adbd5886 WT |
430 | to insert an indication of the origin of a patch at the top of the commit |
431 | message (just after the subject line) to facilitate tracking. For instance, | |
432 | here's what we see in 2.6-stable : | |
433 | ||
434 | Date: Tue May 13 19:10:30 2008 +0000 | |
435 | ||
436 | SCSI: libiscsi regression in 2.6.25: fix nop timer handling | |
437 | ||
438 | commit 4cf1043593db6a337f10e006c23c69e5fc93e722 upstream | |
439 | ||
440 | And here's what appears in 2.4 : | |
441 | ||
442 | Date: Tue May 13 22:12:27 2008 +0200 | |
443 | ||
444 | wireless, airo: waitbusy() won't delay | |
445 | ||
446 | [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a] | |
447 | ||
448 | Whatever the format, this information provides a valuable help to people | |
449 | tracking your trees, and to people trying to trouble-shoot bugs in your | |
450 | tree. | |
451 | ||
1da177e4 | 452 | |
ef40203a | 453 | 13) When to use Acked-by: and Cc: |
0a920b5b | 454 | |
0f44cd23 AM |
455 | The Signed-off-by: tag indicates that the signer was involved in the |
456 | development of the patch, or that he/she was in the patch's delivery path. | |
457 | ||
458 | If a person was not directly involved in the preparation or handling of a | |
459 | patch but wishes to signify and record their approval of it then they can | |
460 | arrange to have an Acked-by: line added to the patch's changelog. | |
461 | ||
462 | Acked-by: is often used by the maintainer of the affected code when that | |
463 | maintainer neither contributed to nor forwarded the patch. | |
464 | ||
465 | Acked-by: is not as formal as Signed-off-by:. It is a record that the acker | |
466 | has at least reviewed the patch and has indicated acceptance. Hence patch | |
467 | mergers will sometimes manually convert an acker's "yep, looks good to me" | |
468 | into an Acked-by:. | |
469 | ||
470 | Acked-by: does not necessarily indicate acknowledgement of the entire patch. | |
471 | For example, if a patch affects multiple subsystems and has an Acked-by: from | |
472 | one subsystem maintainer then this usually indicates acknowledgement of just | |
473 | the part which affects that maintainer's code. Judgement should be used here. | |
ef40203a | 474 | When in doubt people should refer to the original discussion in the mailing |
0f44cd23 AM |
475 | list archives. |
476 | ||
ef40203a JC |
477 | If a person has had the opportunity to comment on a patch, but has not |
478 | provided such comments, you may optionally add a "Cc:" tag to the patch. | |
479 | This is the only tag which might be added without an explicit action by the | |
480 | person it names. This tag documents that potentially interested parties | |
481 | have been included in the discussion | |
0f44cd23 | 482 | |
ef40203a | 483 | |
8401aa1f | 484 | 14) Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes: |
bbb0a424 JC |
485 | |
486 | If this patch fixes a problem reported by somebody else, consider adding a | |
487 | Reported-by: tag to credit the reporter for their contribution. Please | |
488 | note that this tag should not be added without the reporter's permission, | |
489 | especially if the problem was not reported in a public forum. That said, | |
490 | if we diligently credit our bug reporters, they will, hopefully, be | |
491 | inspired to help us again in the future. | |
ef40203a JC |
492 | |
493 | A Tested-by: tag indicates that the patch has been successfully tested (in | |
494 | some environment) by the person named. This tag informs maintainers that | |
495 | some testing has been performed, provides a means to locate testers for | |
496 | future patches, and ensures credit for the testers. | |
497 | ||
498 | Reviewed-by:, instead, indicates that the patch has been reviewed and found | |
499 | acceptable according to the Reviewer's Statement: | |
500 | ||
501 | Reviewer's statement of oversight | |
502 | ||
503 | By offering my Reviewed-by: tag, I state that: | |
504 | ||
505 | (a) I have carried out a technical review of this patch to | |
506 | evaluate its appropriateness and readiness for inclusion into | |
507 | the mainline kernel. | |
508 | ||
509 | (b) Any problems, concerns, or questions relating to the patch | |
510 | have been communicated back to the submitter. I am satisfied | |
511 | with the submitter's response to my comments. | |
512 | ||
513 | (c) While there may be things that could be improved with this | |
514 | submission, I believe that it is, at this time, (1) a | |
515 | worthwhile modification to the kernel, and (2) free of known | |
516 | issues which would argue against its inclusion. | |
517 | ||
518 | (d) While I have reviewed the patch and believe it to be sound, I | |
519 | do not (unless explicitly stated elsewhere) make any | |
520 | warranties or guarantees that it will achieve its stated | |
521 | purpose or function properly in any given situation. | |
522 | ||
523 | A Reviewed-by tag is a statement of opinion that the patch is an | |
524 | appropriate modification of the kernel without any remaining serious | |
525 | technical issues. Any interested reviewer (who has done the work) can | |
526 | offer a Reviewed-by tag for a patch. This tag serves to give credit to | |
527 | reviewers and to inform maintainers of the degree of review which has been | |
528 | done on the patch. Reviewed-by: tags, when supplied by reviewers known to | |
529 | understand the subject area and to perform thorough reviews, will normally | |
5801da1b | 530 | increase the likelihood of your patch getting into the kernel. |
ef40203a | 531 | |
8543ae12 M |
532 | A Suggested-by: tag indicates that the patch idea is suggested by the person |
533 | named and ensures credit to the person for the idea. Please note that this | |
534 | tag should not be added without the reporter's permission, especially if the | |
535 | idea was not posted in a public forum. That said, if we diligently credit our | |
536 | idea reporters, they will, hopefully, be inspired to help us again in the | |
537 | future. | |
538 | ||
8401aa1f JK |
539 | A Fixes: tag indicates that the patch fixes an issue in a previous commit. It |
540 | is used to make it easy to determine where a bug originated, which can help | |
541 | review a bug fix. This tag also assists the stable kernel team in determining | |
542 | which stable kernel versions should receive your fix. This is the preferred | |
543 | method for indicating a bug fixed by the patch. See #2 above for more details. | |
544 | ||
ef40203a JC |
545 | |
546 | 15) The canonical patch format | |
84da7c08 | 547 | |
75f8426c PJ |
548 | The canonical patch subject line is: |
549 | ||
d6b9acc0 | 550 | Subject: [PATCH 001/123] subsystem: summary phrase |
75f8426c PJ |
551 | |
552 | The canonical patch message body contains the following: | |
553 | ||
554 | - A "from" line specifying the patch author. | |
555 | ||
556 | - An empty line. | |
557 | ||
558 | - The body of the explanation, which will be copied to the | |
559 | permanent changelog to describe this patch. | |
560 | ||
561 | - The "Signed-off-by:" lines, described above, which will | |
562 | also go in the changelog. | |
563 | ||
564 | - A marker line containing simply "---". | |
565 | ||
566 | - Any additional comments not suitable for the changelog. | |
567 | ||
568 | - The actual patch (diff output). | |
569 | ||
570 | The Subject line format makes it very easy to sort the emails | |
571 | alphabetically by subject line - pretty much any email reader will | |
572 | support that - since because the sequence number is zero-padded, | |
573 | the numerical and alphabetic sort is the same. | |
574 | ||
d6b9acc0 PJ |
575 | The "subsystem" in the email's Subject should identify which |
576 | area or subsystem of the kernel is being patched. | |
577 | ||
578 | The "summary phrase" in the email's Subject should concisely | |
579 | describe the patch which that email contains. The "summary | |
580 | phrase" should not be a filename. Do not use the same "summary | |
66effdc6 RD |
581 | phrase" for every patch in a whole patch series (where a "patch |
582 | series" is an ordered sequence of multiple, related patches). | |
d6b9acc0 | 583 | |
2ae19aca TT |
584 | Bear in mind that the "summary phrase" of your email becomes a |
585 | globally-unique identifier for that patch. It propagates all the way | |
586 | into the git changelog. The "summary phrase" may later be used in | |
587 | developer discussions which refer to the patch. People will want to | |
588 | google for the "summary phrase" to read discussion regarding that | |
589 | patch. It will also be the only thing that people may quickly see | |
590 | when, two or three months later, they are going through perhaps | |
591 | thousands of patches using tools such as "gitk" or "git log | |
592 | --oneline". | |
593 | ||
594 | For these reasons, the "summary" must be no more than 70-75 | |
595 | characters, and it must describe both what the patch changes, as well | |
596 | as why the patch might be necessary. It is challenging to be both | |
597 | succinct and descriptive, but that is what a well-written summary | |
598 | should do. | |
599 | ||
600 | The "summary phrase" may be prefixed by tags enclosed in square | |
601 | brackets: "Subject: [PATCH tag] <summary phrase>". The tags are not | |
602 | considered part of the summary phrase, but describe how the patch | |
603 | should be treated. Common tags might include a version descriptor if | |
604 | the multiple versions of the patch have been sent out in response to | |
605 | comments (i.e., "v1, v2, v3"), or "RFC" to indicate a request for | |
606 | comments. If there are four patches in a patch series the individual | |
607 | patches may be numbered like this: 1/4, 2/4, 3/4, 4/4. This assures | |
608 | that developers understand the order in which the patches should be | |
609 | applied and that they have reviewed or applied all of the patches in | |
610 | the patch series. | |
d6b9acc0 PJ |
611 | |
612 | A couple of example Subjects: | |
613 | ||
614 | Subject: [patch 2/5] ext2: improve scalability of bitmap searching | |
615 | Subject: [PATCHv2 001/207] x86: fix eflags tracking | |
75f8426c PJ |
616 | |
617 | The "from" line must be the very first line in the message body, | |
618 | and has the form: | |
619 | ||
620 | From: Original Author <author@example.com> | |
621 | ||
622 | The "from" line specifies who will be credited as the author of the | |
623 | patch in the permanent changelog. If the "from" line is missing, | |
624 | then the "From:" line from the email header will be used to determine | |
625 | the patch author in the changelog. | |
626 | ||
627 | The explanation body will be committed to the permanent source | |
628 | changelog, so should make sense to a competent reader who has long | |
629 | since forgotten the immediate details of the discussion that might | |
2ae19aca TT |
630 | have led to this patch. Including symptoms of the failure which the |
631 | patch addresses (kernel log messages, oops messages, etc.) is | |
632 | especially useful for people who might be searching the commit logs | |
633 | looking for the applicable patch. If a patch fixes a compile failure, | |
634 | it may not be necessary to include _all_ of the compile failures; just | |
635 | enough that it is likely that someone searching for the patch can find | |
636 | it. As in the "summary phrase", it is important to be both succinct as | |
637 | well as descriptive. | |
75f8426c PJ |
638 | |
639 | The "---" marker line serves the essential purpose of marking for patch | |
640 | handling tools where the changelog message ends. | |
641 | ||
642 | One good use for the additional comments after the "---" marker is for | |
2ae19aca TT |
643 | a diffstat, to show what files have changed, and the number of |
644 | inserted and deleted lines per file. A diffstat is especially useful | |
645 | on bigger patches. Other comments relevant only to the moment or the | |
646 | maintainer, not suitable for the permanent changelog, should also go | |
647 | here. A good example of such comments might be "patch changelogs" | |
648 | which describe what has changed between the v1 and v2 version of the | |
649 | patch. | |
650 | ||
651 | If you are going to include a diffstat after the "---" marker, please | |
652 | use diffstat options "-p 1 -w 70" so that filenames are listed from | |
653 | the top of the kernel source tree and don't use too much horizontal | |
8e3072a2 JT |
654 | space (easily fit in 80 columns, maybe with some indentation). (git |
655 | generates appropriate diffstats by default.) | |
75f8426c PJ |
656 | |
657 | See more details on the proper patch format in the following | |
658 | references. | |
659 | ||
660 | ||
14863617 | 661 | 16) Sending "git pull" requests (from Linus emails) |
84da7c08 | 662 | |
14863617 RD |
663 | Please write the git repo address and branch name alone on the same line |
664 | so that I can't even by mistake pull from the wrong branch, and so | |
665 | that a triple-click just selects the whole thing. | |
666 | ||
667 | So the proper format is something along the lines of: | |
668 | ||
669 | "Please pull from | |
670 | ||
671 | git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus | |
672 | ||
673 | to get these changes:" | |
674 | ||
675 | so that I don't have to hunt-and-peck for the address and inevitably | |
676 | get it wrong (actually, I've only gotten it wrong a few times, and | |
677 | checking against the diffstat tells me when I get it wrong, but I'm | |
678 | just a lot more comfortable when I don't have to "look for" the right | |
679 | thing to pull, and double-check that I have the right branch-name). | |
680 | ||
681 | ||
682 | Please use "git diff -M --stat --summary" to generate the diffstat: | |
683 | the -M enables rename detection, and the summary enables a summary of | |
684 | new/deleted or renamed files. | |
685 | ||
686 | With rename detection, the statistics are rather different [...] | |
687 | because git will notice that a fair number of the changes are renames. | |
84da7c08 | 688 | |
1da177e4 LT |
689 | ----------------------------------- |
690 | SECTION 2 - HINTS, TIPS, AND TRICKS | |
691 | ----------------------------------- | |
692 | ||
693 | This section lists many of the common "rules" associated with code | |
694 | submitted to the kernel. There are always exceptions... but you must | |
695 | have a really good reason for doing so. You could probably call this | |
696 | section Linus Computer Science 101. | |
697 | ||
698 | ||
699 | ||
700 | 1) Read Documentation/CodingStyle | |
701 | ||
702 | Nuff said. If your code deviates too much from this, it is likely | |
703 | to be rejected without further review, and without comment. | |
704 | ||
5ab3bd57 KK |
705 | One significant exception is when moving code from one file to |
706 | another -- in this case you should not modify the moved code at all in | |
de7d4f0e AW |
707 | the same patch which moves it. This clearly delineates the act of |
708 | moving the code and your changes. This greatly aids review of the | |
709 | actual differences and allows tools to better track the history of | |
710 | the code itself. | |
711 | ||
0a920b5b | 712 | Check your patches with the patch style checker prior to submission |
de7d4f0e AW |
713 | (scripts/checkpatch.pl). The style checker should be viewed as |
714 | a guide not as the final word. If your code looks better with | |
715 | a violation then its probably best left alone. | |
716 | ||
717 | The checker reports at three levels: | |
718 | - ERROR: things that are very likely to be wrong | |
719 | - WARNING: things requiring careful review | |
720 | - CHECK: things requiring thought | |
721 | ||
722 | You should be able to justify all violations that remain in your | |
723 | patch. | |
0a920b5b | 724 | |
1da177e4 LT |
725 | |
726 | ||
727 | 2) #ifdefs are ugly | |
728 | ||
729 | Code cluttered with ifdefs is difficult to read and maintain. Don't do | |
730 | it. Instead, put your ifdefs in a header, and conditionally define | |
731 | 'static inline' functions, or macros, which are used in the code. | |
732 | Let the compiler optimize away the "no-op" case. | |
733 | ||
734 | Simple example, of poor code: | |
735 | ||
736 | dev = alloc_etherdev (sizeof(struct funky_private)); | |
737 | if (!dev) | |
738 | return -ENODEV; | |
739 | #ifdef CONFIG_NET_FUNKINESS | |
740 | init_funky_net(dev); | |
741 | #endif | |
742 | ||
743 | Cleaned-up example: | |
744 | ||
745 | (in header) | |
746 | #ifndef CONFIG_NET_FUNKINESS | |
747 | static inline void init_funky_net (struct net_device *d) {} | |
748 | #endif | |
749 | ||
750 | (in the code itself) | |
751 | dev = alloc_etherdev (sizeof(struct funky_private)); | |
752 | if (!dev) | |
753 | return -ENODEV; | |
754 | init_funky_net(dev); | |
755 | ||
756 | ||
757 | ||
758 | 3) 'static inline' is better than a macro | |
759 | ||
760 | Static inline functions are greatly preferred over macros. | |
761 | They provide type safety, have no length limitations, no formatting | |
762 | limitations, and under gcc they are as cheap as macros. | |
763 | ||
764 | Macros should only be used for cases where a static inline is clearly | |
f2b2ea69 | 765 | suboptimal [there are a few, isolated cases of this in fast paths], |
1da177e4 LT |
766 | or where it is impossible to use a static inline function [such as |
767 | string-izing]. | |
768 | ||
769 | 'static inline' is preferred over 'static __inline__', 'extern inline', | |
770 | and 'extern __inline__'. | |
771 | ||
772 | ||
773 | ||
774 | 4) Don't over-design. | |
775 | ||
776 | Don't try to anticipate nebulous future cases which may or may not | |
84da7c08 | 777 | be useful: "Make it as simple as you can, and no simpler." |
1da177e4 | 778 | |
5b0ed2c6 XVP |
779 | |
780 | ||
781 | ---------------------- | |
782 | SECTION 3 - REFERENCES | |
783 | ---------------------- | |
784 | ||
785 | Andrew Morton, "The perfect patch" (tpp). | |
37c703f4 | 786 | <http://www.ozlabs.org/~akpm/stuff/tpp.txt> |
5b0ed2c6 | 787 | |
8e9cb8fd | 788 | Jeff Garzik, "Linux kernel patch submission format". |
5b0ed2c6 XVP |
789 | <http://linux.yyz.us/patch-format.html> |
790 | ||
8e9cb8fd | 791 | Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". |
f5039935 VN |
792 | <http://www.kroah.com/log/linux/maintainer.html> |
793 | <http://www.kroah.com/log/linux/maintainer-02.html> | |
794 | <http://www.kroah.com/log/linux/maintainer-03.html> | |
795 | <http://www.kroah.com/log/linux/maintainer-04.html> | |
796 | <http://www.kroah.com/log/linux/maintainer-05.html> | |
7e0dae61 | 797 | <http://www.kroah.com/log/linux/maintainer-06.html> |
5b0ed2c6 | 798 | |
bc7455fa | 799 | NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! |
37c703f4 | 800 | <https://lkml.org/lkml/2005/7/11/336> |
5b0ed2c6 | 801 | |
8e9cb8fd | 802 | Kernel Documentation/CodingStyle: |
4db29c17 | 803 | <http://users.sosdg.org/~qiyong/lxr/source/Documentation/CodingStyle> |
5b0ed2c6 | 804 | |
8e9cb8fd | 805 | Linus Torvalds's mail on the canonical patch format: |
5b0ed2c6 | 806 | <http://lkml.org/lkml/2005/4/7/183> |
9536727e AK |
807 | |
808 | Andi Kleen, "On submitting kernel patches" | |
25985edc | 809 | Some strategies to get difficult or controversial changes in. |
9536727e AK |
810 | http://halobates.de/on-submitting-patches.pdf |
811 | ||
5b0ed2c6 | 812 | -- |