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