Commit | Line | Data |
---|---|---|
609d99a3 | 1 | .. _submittingpatches: |
1da177e4 | 2 | |
89edeedd JC |
3 | Submitting patches: the essential guide to getting your code into the kernel |
4 | ============================================================================ | |
1da177e4 LT |
5 | |
6 | For a person or company who wishes to submit a change to the Linux | |
7 | kernel, the process can sometimes be daunting if you're not familiar | |
8 | with "the system." This text is a collection of suggestions which | |
9 | can greatly increase the chances of your change being accepted. | |
10 | ||
d00c4559 JC |
11 | This document contains a large number of suggestions in a relatively terse |
12 | format. For detailed information on how the kernel development process | |
9912d0bb MCC |
13 | works, see Documentation/process/development-process.rst. Also, read |
14 | Documentation/process/submit-checklist.rst | |
9db370de LB |
15 | for a list of items to check before submitting code. |
16 | For device tree binding patches, read | |
aa9b5e0d | 17 | Documentation/devicetree/bindings/submitting-patches.rst. |
1da177e4 | 18 | |
9f364b60 DD |
19 | This documentation assumes that you're using ``git`` to prepare your patches. |
20 | If you're unfamiliar with ``git``, you would be well-advised to learn how to | |
21 | use it, it will make your life as a kernel developer and in general much | |
22 | easier. | |
1da177e4 | 23 | |
604370e1 | 24 | Some subsystems and maintainer trees have additional information about |
b96ff02a MCC |
25 | their workflow and expectations, see |
26 | :ref:`Documentation/process/maintainer-handbooks.rst <maintainer_handbooks_main>`. | |
604370e1 | 27 | |
ef227c39 DD |
28 | Obtain a current source tree |
29 | ---------------------------- | |
7994cc15 JC |
30 | |
31 | If you do not have a repository with the current kernel source handy, use | |
9b2c7677 | 32 | ``git`` to obtain one. You'll want to start with the mainline repository, |
5903019b | 33 | which can be grabbed with:: |
7994cc15 | 34 | |
5903019b | 35 | git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git |
7994cc15 JC |
36 | |
37 | Note, however, that you may not want to develop against the mainline tree | |
38 | directly. Most subsystem maintainers run their own trees and want to see | |
5903019b | 39 | patches prepared against those trees. See the **T:** entry for the subsystem |
7994cc15 JC |
40 | in the MAINTAINERS file to find that tree, or simply ask the maintainer if |
41 | the tree is not listed there. | |
42 | ||
5903019b | 43 | .. _describe_changes: |
84da7c08 | 44 | |
ef227c39 DD |
45 | Describe your changes |
46 | --------------------- | |
1da177e4 | 47 | |
7b9828d4 JW |
48 | Describe your problem. Whether your patch is a one-line bug fix or |
49 | 5000 lines of a new feature, there must be an underlying problem that | |
50 | motivated you to do this work. Convince the reviewer that there is a | |
51 | problem worth fixing and that it makes sense for them to read past the | |
52 | first paragraph. | |
53 | ||
54 | Describe user-visible impact. Straight up crashes and lockups are | |
55 | pretty convincing, but not all bugs are that blatant. Even if the | |
56 | problem was spotted during code review, describe the impact you think | |
57 | it can have on users. Keep in mind that the majority of Linux | |
58 | installations run kernels from secondary stable trees or | |
59 | vendor/product-specific trees that cherry-pick only specific patches | |
60 | from upstream, so include anything that could help route your change | |
61 | downstream: provoking circumstances, excerpts from dmesg, crash | |
62 | descriptions, performance regressions, latency spikes, lockups, etc. | |
63 | ||
64 | Quantify optimizations and trade-offs. If you claim improvements in | |
65 | performance, memory consumption, stack footprint, or binary size, | |
66 | include numbers that back them up. But also describe non-obvious | |
67 | costs. Optimizations usually aren't free but trade-offs between CPU, | |
68 | memory, and readability; or, when it comes to heuristics, between | |
69 | different workloads. Describe the expected downsides of your | |
70 | optimization so that the reviewer can weigh costs against benefits. | |
71 | ||
72 | Once the problem is established, describe what you are actually doing | |
73 | about it in technical detail. It's important to describe the change | |
74 | in plain English for the reviewer to verify that the code is behaving | |
75 | as you intend it to. | |
1da177e4 | 76 | |
2ae19aca TT |
77 | The maintainer will thank you if you write your patch description in a |
78 | form which can be easily pulled into Linux's source code management | |
6d5aa418 | 79 | system, ``git``, as a "commit log". See :ref:`the_canonical_patch_format`. |
2ae19aca | 80 | |
7b9828d4 JW |
81 | Solve only one problem per patch. If your description starts to get |
82 | long, that's a sign that you probably need to split up your patch. | |
5903019b | 83 | See :ref:`split_changes`. |
1da177e4 | 84 | |
d89b1945 RD |
85 | When you submit or resubmit a patch or patch series, include the |
86 | complete patch description and justification for it. Don't just | |
87 | say that this is version N of the patch (series). Don't expect the | |
d00c4559 | 88 | subsystem maintainer to refer back to earlier patch versions or referenced |
d89b1945 RD |
89 | URLs to find the patch description and put that into the patch. |
90 | I.e., the patch (series) and its description should be self-contained. | |
d00c4559 | 91 | This benefits both the maintainers and reviewers. Some reviewers |
d89b1945 RD |
92 | probably didn't even receive earlier versions of the patch. |
93 | ||
74a475ac JT |
94 | Describe your changes in imperative mood, e.g. "make xyzzy do frotz" |
95 | instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy | |
96 | to do frotz", as if you are giving orders to the codebase to change | |
97 | its behaviour. | |
98 | ||
0af52703 GU |
99 | If you want to refer to a specific commit, don't just refer to the |
100 | SHA-1 ID of the commit. Please also include the oneline summary of | |
101 | the commit, to make it easier for reviewers to know what it is about. | |
5903019b | 102 | Example:: |
0af52703 GU |
103 | |
104 | Commit e21d2170f36602ae2708 ("video: remove unnecessary | |
105 | platform_set_drvdata()") removed the unnecessary | |
106 | platform_set_drvdata(), but left the variable "dev" unused, | |
107 | delete it. | |
108 | ||
7994cc15 JC |
109 | You should also be sure to use at least the first twelve characters of the |
110 | SHA-1 ID. The kernel repository holds a *lot* of objects, making | |
111 | collisions with shorter IDs a real possibility. Bear in mind that, even if | |
112 | there is no collision with your six-character ID now, that condition may | |
113 | change five years from now. | |
114 | ||
1f57bd42 | 115 | If related discussions or any other background information behind the change |
0d828200 MB |
116 | can be found on the web, add 'Link:' tags pointing to it. If the patch is a |
117 | result of some earlier mailing list discussions or something documented on the | |
118 | web, point to it. | |
1f57bd42 TL |
119 | |
120 | When linking to mailing list archives, preferably use the lore.kernel.org | |
121 | message archiver service. To create the link URL, use the contents of the | |
413e775e | 122 | ``Message-ID`` header of the message without the surrounding angle brackets. |
1f57bd42 TL |
123 | For example:: |
124 | ||
413e775e | 125 | Link: https://lore.kernel.org/30th.anniversary.repost@klaava.Helsinki.FI |
1f57bd42 TL |
126 | |
127 | Please check the link to make sure that it is actually working and points | |
128 | to the relevant message. | |
129 | ||
130 | However, try to make your explanation understandable without external | |
131 | resources. In addition to giving a URL to a mailing list archive or bug, | |
132 | summarize the relevant points of the discussion that led to the | |
133 | patch as submitted. | |
134 | ||
0d828200 MB |
135 | In case your patch fixes a bug, use the 'Closes:' tag with a URL referencing |
136 | the report in the mailing list archives or a public bug tracker. For example:: | |
137 | ||
138 | Closes: https://example.com/issues/1234 | |
139 | ||
140 | Some bug trackers have the ability to close issues automatically when a | |
141 | commit with such a tag is applied. Some bots monitoring mailing lists can | |
142 | also track such tags and take certain actions. Private bug trackers and | |
143 | invalid URLs are forbidden. | |
144 | ||
8401aa1f | 145 | If your patch fixes a bug in a specific commit, e.g. you found an issue using |
9b2c7677 | 146 | ``git bisect``, please use the 'Fixes:' tag with the first 12 characters of |
19c3fe28 SC |
147 | the SHA-1 ID, and the one line summary. Do not split the tag across multiple |
148 | lines, tags are exempt from the "wrap at 75 columns" rule in order to simplify | |
149 | parsing scripts. For example:: | |
8401aa1f | 150 | |
19c3fe28 | 151 | Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed") |
8401aa1f | 152 | |
9b2c7677 MCC |
153 | The following ``git config`` settings can be used to add a pretty format for |
154 | outputting the above style in the ``git log`` or ``git show`` commands:: | |
8401aa1f JK |
155 | |
156 | [core] | |
157 | abbrev = 12 | |
158 | [pretty] | |
159 | fixes = Fixes: %h (\"%s\") | |
1da177e4 | 160 | |
5b5bbb8c TR |
161 | An example call:: |
162 | ||
163 | $ git log -1 --pretty=fixes 54a4f0239f2e | |
164 | Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed") | |
165 | ||
5903019b MCC |
166 | .. _split_changes: |
167 | ||
ef227c39 DD |
168 | Separate your changes |
169 | --------------------- | |
1da177e4 | 170 | |
5903019b | 171 | Separate each **logical change** into a separate patch. |
1da177e4 LT |
172 | |
173 | For example, if your changes include both bug fixes and performance | |
174 | enhancements for a single driver, separate those changes into two | |
175 | or more patches. If your changes include an API update, and a new | |
176 | driver which uses that new API, separate those into two patches. | |
177 | ||
178 | On the other hand, if you make a single change to numerous files, | |
179 | group those changes into a single patch. Thus a single logical change | |
180 | is contained within a single patch. | |
181 | ||
d00c4559 JC |
182 | The point to remember is that each patch should make an easily understood |
183 | change that can be verified by reviewers. Each patch should be justifiable | |
184 | on its own merits. | |
185 | ||
1da177e4 | 186 | If one patch depends on another patch in order for a change to be |
5903019b | 187 | complete, that is OK. Simply note **"this patch depends on patch X"** |
1da177e4 LT |
188 | in your patch description. |
189 | ||
7994cc15 JC |
190 | When dividing your change into a series of patches, take special care to |
191 | ensure that the kernel builds and runs properly after each patch in the | |
5903019b | 192 | series. Developers using ``git bisect`` to track down a problem can end up |
7994cc15 JC |
193 | splitting your patch series at any point; they will not thank you if you |
194 | introduce bugs in the middle. | |
195 | ||
5b0ed2c6 XVP |
196 | If you cannot condense your patch set into a smaller set of patches, |
197 | then only post say 15 or so at a time and wait for review and integration. | |
198 | ||
199 | ||
1da177e4 | 200 | |
ef227c39 DD |
201 | Style-check your changes |
202 | ------------------------ | |
0a920b5b AW |
203 | |
204 | Check your patch for basic style violations, details of which can be | |
9912d0bb | 205 | found in Documentation/process/coding-style.rst. |
dca22a63 | 206 | Failure to do so simply wastes |
f56d35e7 | 207 | the reviewers time and will get your patch rejected, probably |
0a920b5b AW |
208 | without even being read. |
209 | ||
6de16eba JC |
210 | One significant exception is when moving code from one file to |
211 | another -- in this case you should not modify the moved code at all in | |
212 | the same patch which moves it. This clearly delineates the act of | |
213 | moving the code and your changes. This greatly aids review of the | |
214 | actual differences and allows tools to better track the history of | |
215 | the code itself. | |
216 | ||
217 | Check your patches with the patch style checker prior to submission | |
218 | (scripts/checkpatch.pl). Note, though, that the style checker should be | |
219 | viewed as a guide, not as a replacement for human judgment. If your code | |
220 | looks better with a violation then its probably best left alone. | |
0a920b5b | 221 | |
6de16eba JC |
222 | The checker reports at three levels: |
223 | - ERROR: things that are very likely to be wrong | |
224 | - WARNING: things requiring careful review | |
225 | - CHECK: things requiring thought | |
0a920b5b | 226 | |
6de16eba JC |
227 | You should be able to justify all violations that remain in your |
228 | patch. | |
0a920b5b AW |
229 | |
230 | ||
ef227c39 DD |
231 | Select the recipients for your patch |
232 | ------------------------------------ | |
1da177e4 | 233 | |
c0d747a5 KK |
234 | You should always copy the appropriate subsystem maintainer(s) and list(s) on |
235 | any patch to code that they maintain; look through the MAINTAINERS file and the | |
236 | source code revision history to see who those maintainers are. The script | |
237 | scripts/get_maintainer.pl can be very useful at this step (pass paths to your | |
238 | patches as arguments to scripts/get_maintainer.pl). If you cannot find a | |
f1a69399 KK |
239 | maintainer for the subsystem you are working on, Andrew Morton |
240 | (akpm@linux-foundation.org) serves as a maintainer of last resort. | |
1da177e4 | 241 | |
c0d747a5 KK |
242 | linux-kernel@vger.kernel.org should be used by default for all patches, but the |
243 | volume on that list has caused a number of developers to tune it out. Please | |
244 | do not spam unrelated lists and unrelated people, though. | |
1da177e4 | 245 | |
413e775e KR |
246 | Many kernel-related lists are hosted at kernel.org; you can find a list |
247 | of them at https://subspace.kernel.org. There are kernel-related lists | |
248 | hosted elsewhere as well, though. | |
5b0ed2c6 | 249 | |
1da177e4 | 250 | Linus Torvalds is the final arbiter of all changes accepted into the |
e00bfcbf | 251 | Linux kernel. His e-mail address is <torvalds@linux-foundation.org>. |
ccae8616 JC |
252 | He gets a lot of e-mail, and, at this point, very few patches go through |
253 | Linus directly, so typically you should do your best to -avoid- | |
e00bfcbf | 254 | sending him e-mail. |
1da177e4 | 255 | |
ccae8616 JC |
256 | If you have a patch that fixes an exploitable security bug, send that patch |
257 | to security@kernel.org. For severe bugs, a short embargo may be considered | |
253508ca | 258 | to allow distributors to get the patch out to users; in such cases, |
eb45fb2f | 259 | obviously, the patch should not be sent to any public lists. See also |
44ac5aba | 260 | Documentation/process/security-bugs.rst. |
1da177e4 | 261 | |
ccae8616 | 262 | Patches that fix a severe bug in a released kernel should be directed |
5903019b | 263 | toward the stable maintainers by putting a line like this:: |
1da177e4 | 264 | |
ccae8616 | 265 | Cc: stable@vger.kernel.org |
1da177e4 | 266 | |
8cda4c3a | 267 | into the sign-off area of your patch (note, NOT an email recipient). You |
9912d0bb MCC |
268 | should also read Documentation/process/stable-kernel-rules.rst |
269 | in addition to this document. | |
5b0ed2c6 | 270 | |
ccae8616 JC |
271 | If changes affect userland-kernel interfaces, please send the MAN-PAGES |
272 | maintainer (as listed in the MAINTAINERS file) a man-pages patch, or at | |
273 | least a notification of the change, so that some information makes its way | |
274 | into the manual pages. User-space API changes should also be copied to | |
5903019b | 275 | linux-api@vger.kernel.org. |
1da177e4 | 276 | |
1da177e4 | 277 | |
ef227c39 DD |
278 | No MIME, no links, no compression, no attachments. Just plain text |
279 | ------------------------------------------------------------------- | |
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 | ||
9f364b60 DD |
286 | For this reason, all patches should be submitted by e-mail "inline". The |
287 | easiest way to do this is with ``git send-email``, which is strongly | |
288 | recommended. An interactive tutorial for ``git send-email`` is available at | |
289 | https://git-send-email.io. | |
290 | ||
291 | If you choose not to use ``git send-email``: | |
9b2c7677 MCC |
292 | |
293 | .. warning:: | |
294 | ||
295 | Be wary of your editor's word-wrap corrupting your patch, | |
296 | if you choose to cut-n-paste your patch. | |
1da177e4 LT |
297 | |
298 | Do not attach the patch as a MIME attachment, compressed or not. | |
299 | Many popular e-mail applications will not always transmit a MIME | |
300 | attachment as plain text, making it impossible to comment on your | |
301 | code. A MIME attachment also takes Linus a bit more time to process, | |
302 | decreasing the likelihood of your MIME-attached change being accepted. | |
303 | ||
304 | Exception: If your mailer is mangling patches then someone may ask | |
305 | you to re-send them using MIME. | |
306 | ||
9912d0bb MCC |
307 | See Documentation/process/email-clients.rst for hints about configuring |
308 | your e-mail client so that it sends your patches untouched. | |
1da177e4 | 309 | |
ef227c39 DD |
310 | Respond to review comments |
311 | -------------------------- | |
1da177e4 | 312 | |
0eea2314 | 313 | Your patch will almost certainly get comments from reviewers on ways in |
9f364b60 DD |
314 | which the patch can be improved, in the form of a reply to your email. You must |
315 | respond to those comments; ignoring reviewers is a good way to get ignored in | |
316 | return. You can simply reply to their emails to answer their comments. Review | |
317 | comments or questions that do not lead to a code change should almost certainly | |
0eea2314 JC |
318 | bring about a comment or changelog entry so that the next reviewer better |
319 | understands what is going on. | |
1da177e4 | 320 | |
0eea2314 JC |
321 | Be sure to tell the reviewers what changes you are making and to thank them |
322 | for their time. Code review is a tiring and time-consuming process, and | |
323 | reviewers sometimes get grumpy. Even in that case, though, respond | |
0c603a5c KK |
324 | politely and address the problems they have pointed out. When sending a next |
325 | version, add a ``patch changelog`` to the cover letter or to individual patches | |
42da2c00 | 326 | explaining difference against previous submission (see |
0c603a5c | 327 | :ref:`the_canonical_patch_format`). |
1fae02e7 TW |
328 | Notify people that commented on your patch about new versions by adding them to |
329 | the patches CC list. | |
1da177e4 | 330 | |
9912d0bb | 331 | See Documentation/process/email-clients.rst for recommendations on email |
7433ff33 DD |
332 | clients and mailing list etiquette. |
333 | ||
329ac9af KC |
334 | .. _interleaved_replies: |
335 | ||
336 | Use trimmed interleaved replies in email discussions | |
337 | ---------------------------------------------------- | |
338 | Top-posting is strongly discouraged in Linux kernel development | |
339 | discussions. Interleaved (or "inline") replies make conversations much | |
340 | easier to follow. For more details see: | |
341 | https://en.wikipedia.org/wiki/Posting_style#Interleaved_style | |
342 | ||
343 | As is frequently quoted on the mailing list:: | |
344 | ||
345 | A: http://en.wikipedia.org/wiki/Top_post | |
346 | Q: Were do I find info about this thing called top-posting? | |
347 | A: Because it messes up the order in which people normally read text. | |
348 | Q: Why is top-posting such a bad thing? | |
349 | A: Top-posting. | |
350 | Q: What is the most annoying thing in e-mail? | |
351 | ||
352 | Similarly, please trim all unneeded quotations that aren't relevant | |
353 | to your reply. This makes responses easier to find, and saves time and | |
354 | space. For more details see: http://daringfireball.net/2007/07/on_top :: | |
355 | ||
356 | A: No. | |
357 | Q: Should I include quotations after my reply? | |
358 | ||
31c9d7c8 | 359 | .. _resend_reminders: |
1da177e4 | 360 | |
ef227c39 DD |
361 | Don't get discouraged - or impatient |
362 | ------------------------------------ | |
1da177e4 | 363 | |
0eea2314 JC |
364 | After you have submitted your change, be patient and wait. Reviewers are |
365 | busy people and may not get to your patch right away. | |
1da177e4 | 366 | |
0eea2314 JC |
367 | Once upon a time, patches used to disappear into the void without comment, |
368 | but the development process works more smoothly than that now. You should | |
02f99987 MB |
369 | receive comments within a few weeks (typically 2-3); if that does not |
370 | happen, make sure that you have sent your patches to the right place. | |
371 | Wait for a minimum of one week before resubmitting or pinging reviewers | |
372 | - possibly longer during busy times like merge windows. | |
1da177e4 | 373 | |
6349469a BP |
374 | It's also ok to resend the patch or the patch series after a couple of |
375 | weeks with the word "RESEND" added to the subject line:: | |
376 | ||
377 | [PATCH Vx RESEND] sub/sys: Condensed patch summary | |
378 | ||
379 | Don't add "RESEND" when you are submitting a modified version of your | |
380 | patch or patch series - "RESEND" only applies to resubmission of a | |
381 | patch or patch series which have not been modified in any way from the | |
382 | previous submission. | |
1da177e4 | 383 | |
1da177e4 | 384 | |
ef227c39 DD |
385 | Include PATCH in the subject |
386 | ----------------------------- | |
1da177e4 LT |
387 | |
388 | Due to high e-mail traffic to Linus, and to linux-kernel, it is common | |
389 | convention to prefix your subject line with [PATCH]. This lets Linus | |
390 | and other kernel developers more easily distinguish patches from other | |
391 | e-mail discussions. | |
392 | ||
9f364b60 | 393 | ``git send-email`` will do this for you automatically. |
1da177e4 LT |
394 | |
395 | ||
ef227c39 DD |
396 | Sign your work - the Developer's Certificate of Origin |
397 | ------------------------------------------------------ | |
1da177e4 LT |
398 | |
399 | To improve tracking of who did what, especially with patches that can | |
400 | percolate to their final resting place in the kernel through several | |
401 | layers of maintainers, we've introduced a "sign-off" procedure on | |
402 | patches that are being emailed around. | |
403 | ||
404 | The sign-off is a simple line at the end of the explanation for the | |
405 | patch, which certifies that you wrote it or otherwise have the right to | |
db12fb83 | 406 | pass it on as an open-source patch. The rules are pretty simple: if you |
1da177e4 LT |
407 | can certify the below: |
408 | ||
5903019b MCC |
409 | Developer's Certificate of Origin 1.1 |
410 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
1da177e4 | 411 | |
5903019b | 412 | By making a contribution to this project, I certify that: |
1da177e4 LT |
413 | |
414 | (a) The contribution was created in whole or in part by me and I | |
415 | have the right to submit it under the open source license | |
416 | indicated in the file; or | |
417 | ||
418 | (b) The contribution is based upon previous work that, to the best | |
419 | of my knowledge, is covered under an appropriate open source | |
420 | license and I have the right under that license to submit that | |
421 | work with modifications, whether created in whole or in part | |
422 | by me, under the same open source license (unless I am | |
423 | permitted to submit under a different license), as indicated | |
424 | in the file; or | |
425 | ||
426 | (c) The contribution was provided directly to me by some other | |
427 | person who certified (a), (b) or (c) and I have not modified | |
428 | it. | |
429 | ||
e00bfcbf SB |
430 | (d) I understand and agree that this project and the contribution |
431 | are public and that a record of the contribution (including all | |
432 | personal information I submit with it, including my sign-off) is | |
433 | maintained indefinitely and may be redistributed consistent with | |
434 | this project or the open source license(s) involved. | |
cbd83da8 | 435 | |
5903019b | 436 | then you just add a line saying:: |
1da177e4 | 437 | |
9fd5559c | 438 | Signed-off-by: Random J Developer <random@developer.example.org> |
1da177e4 | 439 | |
d4563201 | 440 | using a known identity (sorry, no anonymous contributions.) |
9f364b60 | 441 | This will be done for you automatically if you use ``git commit -s``. |
7d717887 AS |
442 | Reverts should also include "Signed-off-by". ``git revert -s`` does that |
443 | for you. | |
af45f32d | 444 | |
1da177e4 LT |
445 | Some people also put extra tags at the end. They'll just be ignored for |
446 | now, but you can do this to mark internal company procedures or just | |
e00bfcbf | 447 | point out some special detail about the sign-off. |
1da177e4 | 448 | |
9bf19b78 BP |
449 | Any further SoBs (Signed-off-by:'s) following the author's SoB are from |
450 | people handling and transporting the patch, but were not involved in its | |
451 | development. SoB chains should reflect the **real** route a patch took | |
452 | as it was propagated to the maintainers and ultimately to Linus, with | |
453 | the first SoB entry signalling primary authorship of a single author. | |
454 | ||
1da177e4 | 455 | |
ef227c39 DD |
456 | When to use Acked-by:, Cc:, and Co-developed-by: |
457 | ------------------------------------------------ | |
0a920b5b | 458 | |
0f44cd23 AM |
459 | The Signed-off-by: tag indicates that the signer was involved in the |
460 | development of the patch, or that he/she was in the patch's delivery path. | |
461 | ||
462 | If a person was not directly involved in the preparation or handling of a | |
463 | patch but wishes to signify and record their approval of it then they can | |
d00c4559 | 464 | ask to have an Acked-by: line added to the patch's changelog. |
0f44cd23 AM |
465 | |
466 | Acked-by: is often used by the maintainer of the affected code when that | |
467 | maintainer neither contributed to nor forwarded the patch. | |
468 | ||
469 | Acked-by: is not as formal as Signed-off-by:. It is a record that the acker | |
470 | has at least reviewed the patch and has indicated acceptance. Hence patch | |
471 | mergers will sometimes manually convert an acker's "yep, looks good to me" | |
d00c4559 JC |
472 | into an Acked-by: (but note that it is usually better to ask for an |
473 | explicit ack). | |
0f44cd23 AM |
474 | |
475 | Acked-by: does not necessarily indicate acknowledgement of the entire patch. | |
476 | For example, if a patch affects multiple subsystems and has an Acked-by: from | |
477 | one subsystem maintainer then this usually indicates acknowledgement of just | |
478 | the part which affects that maintainer's code. Judgement should be used here. | |
ef40203a | 479 | When in doubt people should refer to the original discussion in the mailing |
0f44cd23 AM |
480 | list archives. |
481 | ||
ef40203a | 482 | If a person has had the opportunity to comment on a patch, but has not |
5903019b | 483 | provided such comments, you may optionally add a ``Cc:`` tag to the patch. |
ef40203a | 484 | This is the only tag which might be added without an explicit action by the |
d00c4559 JC |
485 | person it names - but it should indicate that this person was copied on the |
486 | patch. This tag documents that potentially interested parties | |
487 | have been included in the discussion. | |
0f44cd23 | 488 | |
24a2bb90 | 489 | Co-developed-by: states that the patch was co-created by multiple developers; |
7e902857 | 490 | it is used to give attribution to co-authors (in addition to the author |
24a2bb90 SC |
491 | attributed by the From: tag) when several people work on a single patch. Since |
492 | Co-developed-by: denotes authorship, every Co-developed-by: must be immediately | |
493 | followed by a Signed-off-by: of the associated co-author. Standard sign-off | |
494 | procedure applies, i.e. the ordering of Signed-off-by: tags should reflect the | |
495 | chronological history of the patch insofar as possible, regardless of whether | |
496 | the author is attributed via From: or Co-developed-by:. Notably, the last | |
497 | Signed-off-by: must always be that of the developer submitting the patch. | |
498 | ||
499 | Note, the From: tag is optional when the From: author is also the person (and | |
500 | email) listed in the From: line of the email header. | |
501 | ||
502 | Example of a patch submitted by the From: author:: | |
503 | ||
504 | <changelog> | |
505 | ||
506 | Co-developed-by: First Co-Author <first@coauthor.example.org> | |
507 | Signed-off-by: First Co-Author <first@coauthor.example.org> | |
508 | Co-developed-by: Second Co-Author <second@coauthor.example.org> | |
509 | Signed-off-by: Second Co-Author <second@coauthor.example.org> | |
510 | Signed-off-by: From Author <from@author.example.org> | |
511 | ||
512 | Example of a patch submitted by a Co-developed-by: author:: | |
513 | ||
514 | From: From Author <from@author.example.org> | |
515 | ||
516 | <changelog> | |
517 | ||
518 | Co-developed-by: Random Co-Author <random@coauthor.example.org> | |
519 | Signed-off-by: Random Co-Author <random@coauthor.example.org> | |
520 | Signed-off-by: From Author <from@author.example.org> | |
521 | Co-developed-by: Submitting Co-Author <sub@coauthor.example.org> | |
522 | Signed-off-by: Submitting Co-Author <sub@coauthor.example.org> | |
82d95343 | 523 | |
ef40203a | 524 | |
ef227c39 DD |
525 | Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes: |
526 | ---------------------------------------------------------------------- | |
bbb0a424 | 527 | |
d75ef707 | 528 | The Reported-by tag gives credit to people who find bugs and report them and it |
901578a4 TL |
529 | hopefully inspires them to help us again in the future. The tag is intended for |
530 | bugs; please do not use it to credit feature requests. The tag should be | |
0d828200 MB |
531 | followed by a Closes: tag pointing to the report, unless the report is not |
532 | available on the web. The Link: tag can be used instead of Closes: if the patch | |
533 | fixes a part of the issue(s) being reported. Please note that if the bug was | |
534 | reported in private, then ask for permission first before using the Reported-by | |
535 | tag. | |
ef40203a JC |
536 | |
537 | A Tested-by: tag indicates that the patch has been successfully tested (in | |
538 | some environment) by the person named. This tag informs maintainers that | |
539 | some testing has been performed, provides a means to locate testers for | |
540 | future patches, and ensures credit for the testers. | |
541 | ||
542 | Reviewed-by:, instead, indicates that the patch has been reviewed and found | |
543 | acceptable according to the Reviewer's Statement: | |
544 | ||
5903019b MCC |
545 | Reviewer's statement of oversight |
546 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
ef40203a | 547 | |
5903019b | 548 | By offering my Reviewed-by: tag, I state that: |
ef40203a | 549 | |
5903019b | 550 | (a) I have carried out a technical review of this patch to |
ef40203a JC |
551 | evaluate its appropriateness and readiness for inclusion into |
552 | the mainline kernel. | |
553 | ||
554 | (b) Any problems, concerns, or questions relating to the patch | |
555 | have been communicated back to the submitter. I am satisfied | |
556 | with the submitter's response to my comments. | |
557 | ||
558 | (c) While there may be things that could be improved with this | |
559 | submission, I believe that it is, at this time, (1) a | |
560 | worthwhile modification to the kernel, and (2) free of known | |
561 | issues which would argue against its inclusion. | |
562 | ||
563 | (d) While I have reviewed the patch and believe it to be sound, I | |
564 | do not (unless explicitly stated elsewhere) make any | |
565 | warranties or guarantees that it will achieve its stated | |
566 | purpose or function properly in any given situation. | |
567 | ||
568 | A Reviewed-by tag is a statement of opinion that the patch is an | |
569 | appropriate modification of the kernel without any remaining serious | |
570 | technical issues. Any interested reviewer (who has done the work) can | |
571 | offer a Reviewed-by tag for a patch. This tag serves to give credit to | |
572 | reviewers and to inform maintainers of the degree of review which has been | |
573 | done on the patch. Reviewed-by: tags, when supplied by reviewers known to | |
574 | understand the subject area and to perform thorough reviews, will normally | |
5801da1b | 575 | increase the likelihood of your patch getting into the kernel. |
ef40203a | 576 | |
030f066f KK |
577 | Both Tested-by and Reviewed-by tags, once received on mailing list from tester |
578 | or reviewer, should be added by author to the applicable patches when sending | |
579 | next versions. However if the patch has changed substantially in following | |
580 | version, these tags might not be applicable anymore and thus should be removed. | |
581 | Usually removal of someone's Tested-by or Reviewed-by tags should be mentioned | |
582 | in the patch changelog (after the '---' separator). | |
583 | ||
8543ae12 M |
584 | A Suggested-by: tag indicates that the patch idea is suggested by the person |
585 | named and ensures credit to the person for the idea. Please note that this | |
586 | tag should not be added without the reporter's permission, especially if the | |
587 | idea was not posted in a public forum. That said, if we diligently credit our | |
588 | idea reporters, they will, hopefully, be inspired to help us again in the | |
589 | future. | |
590 | ||
8401aa1f JK |
591 | A Fixes: tag indicates that the patch fixes an issue in a previous commit. It |
592 | is used to make it easy to determine where a bug originated, which can help | |
593 | review a bug fix. This tag also assists the stable kernel team in determining | |
594 | which stable kernel versions should receive your fix. This is the preferred | |
5903019b MCC |
595 | method for indicating a bug fixed by the patch. See :ref:`describe_changes` |
596 | for more details. | |
8401aa1f | 597 | |
f0ea149e | 598 | Note: Attaching a Fixes: tag does not subvert the stable kernel rules |
9912d0bb | 599 | process nor the requirement to Cc: stable@vger.kernel.org on all stable |
f0ea149e | 600 | patch candidates. For more information, please read |
9912d0bb MCC |
601 | Documentation/process/stable-kernel-rules.rst. |
602 | ||
f58252cd | 603 | .. _the_canonical_patch_format: |
ef40203a | 604 | |
ef227c39 DD |
605 | The canonical patch format |
606 | -------------------------- | |
7994cc15 JC |
607 | |
608 | This section describes how the patch itself should be formatted. Note | |
9b2c7677 | 609 | that, if you have your patches stored in a ``git`` repository, proper patch |
5903019b | 610 | formatting can be had with ``git format-patch``. The tools cannot create |
7994cc15 | 611 | the necessary text, though, so read the instructions below anyway. |
84da7c08 | 612 | |
5903019b | 613 | The canonical patch subject line is:: |
75f8426c | 614 | |
d6b9acc0 | 615 | Subject: [PATCH 001/123] subsystem: summary phrase |
75f8426c PJ |
616 | |
617 | The canonical patch message body contains the following: | |
618 | ||
d19b3e32 JH |
619 | - A ``from`` line specifying the patch author, followed by an empty |
620 | line (only needed if the person sending the patch is not the author). | |
75f8426c | 621 | |
2a076f40 JP |
622 | - The body of the explanation, line wrapped at 75 columns, which will |
623 | be copied to the permanent changelog to describe this patch. | |
75f8426c | 624 | |
d19b3e32 JH |
625 | - An empty line. |
626 | ||
5903019b | 627 | - The ``Signed-off-by:`` lines, described above, which will |
75f8426c PJ |
628 | also go in the changelog. |
629 | ||
5903019b | 630 | - A marker line containing simply ``---``. |
75f8426c PJ |
631 | |
632 | - Any additional comments not suitable for the changelog. | |
633 | ||
9b2c7677 | 634 | - The actual patch (``diff`` output). |
75f8426c PJ |
635 | |
636 | The Subject line format makes it very easy to sort the emails | |
637 | alphabetically by subject line - pretty much any email reader will | |
638 | support that - since because the sequence number is zero-padded, | |
639 | the numerical and alphabetic sort is the same. | |
640 | ||
5903019b | 641 | The ``subsystem`` in the email's Subject should identify which |
d6b9acc0 PJ |
642 | area or subsystem of the kernel is being patched. |
643 | ||
5903019b MCC |
644 | The ``summary phrase`` in the email's Subject should concisely |
645 | describe the patch which that email contains. The ``summary | |
646 | phrase`` should not be a filename. Do not use the same ``summary | |
647 | phrase`` for every patch in a whole patch series (where a ``patch | |
648 | series`` is an ordered sequence of multiple, related patches). | |
d6b9acc0 | 649 | |
5903019b | 650 | Bear in mind that the ``summary phrase`` of your email becomes a |
2ae19aca | 651 | globally-unique identifier for that patch. It propagates all the way |
9b2c7677 | 652 | into the ``git`` changelog. The ``summary phrase`` may later be used in |
2ae19aca | 653 | developer discussions which refer to the patch. People will want to |
5903019b | 654 | google for the ``summary phrase`` to read discussion regarding that |
2ae19aca TT |
655 | patch. It will also be the only thing that people may quickly see |
656 | when, two or three months later, they are going through perhaps | |
9b2c7677 MCC |
657 | thousands of patches using tools such as ``gitk`` or ``git log |
658 | --oneline``. | |
2ae19aca | 659 | |
5903019b | 660 | For these reasons, the ``summary`` must be no more than 70-75 |
2ae19aca TT |
661 | characters, and it must describe both what the patch changes, as well |
662 | as why the patch might be necessary. It is challenging to be both | |
663 | succinct and descriptive, but that is what a well-written summary | |
664 | should do. | |
665 | ||
5903019b | 666 | The ``summary phrase`` may be prefixed by tags enclosed in square |
e12d7462 AH |
667 | brackets: "Subject: [PATCH <tag>...] <summary phrase>". The tags are |
668 | not considered part of the summary phrase, but describe how the patch | |
2ae19aca TT |
669 | should be treated. Common tags might include a version descriptor if |
670 | the multiple versions of the patch have been sent out in response to | |
671 | comments (i.e., "v1, v2, v3"), or "RFC" to indicate a request for | |
875f82cb | 672 | comments. |
d6b9acc0 | 673 | |
875f82cb BP |
674 | If there are four patches in a patch series the individual patches may |
675 | be numbered like this: 1/4, 2/4, 3/4, 4/4. This assures that developers | |
676 | understand the order in which the patches should be applied and that | |
677 | they have reviewed or applied all of the patches in the patch series. | |
678 | ||
679 | Here are some good example Subjects:: | |
d6b9acc0 | 680 | |
e12d7462 AH |
681 | Subject: [PATCH 2/5] ext2: improve scalability of bitmap searching |
682 | Subject: [PATCH v2 01/27] x86: fix eflags tracking | |
875f82cb BP |
683 | Subject: [PATCH v2] sub/sys: Condensed patch summary |
684 | Subject: [PATCH v2 M/N] sub/sys: Condensed patch summary | |
75f8426c | 685 | |
5903019b | 686 | The ``from`` line must be the very first line in the message body, |
75f8426c PJ |
687 | and has the form: |
688 | ||
24a2bb90 | 689 | From: Patch Author <author@example.com> |
75f8426c | 690 | |
5903019b MCC |
691 | The ``from`` line specifies who will be credited as the author of the |
692 | patch in the permanent changelog. If the ``from`` line is missing, | |
693 | then the ``From:`` line from the email header will be used to determine | |
75f8426c PJ |
694 | the patch author in the changelog. |
695 | ||
696 | The explanation body will be committed to the permanent source | |
875f82cb BP |
697 | changelog, so should make sense to a competent reader who has long since |
698 | forgotten the immediate details of the discussion that might have led to | |
699 | this patch. Including symptoms of the failure which the patch addresses | |
700 | (kernel log messages, oops messages, etc.) are especially useful for | |
701 | people who might be searching the commit logs looking for the applicable | |
702 | patch. The text should be written in such detail so that when read | |
703 | weeks, months or even years later, it can give the reader the needed | |
704 | details to grasp the reasoning for **why** the patch was created. | |
705 | ||
706 | If a patch fixes a compile failure, it may not be necessary to include | |
707 | _all_ of the compile failures; just enough that it is likely that | |
708 | someone searching for the patch can find it. As in the ``summary | |
709 | phrase``, it is important to be both succinct as well as descriptive. | |
710 | ||
711 | The ``---`` marker line serves the essential purpose of marking for | |
712 | patch handling tools where the changelog message ends. | |
713 | ||
714 | One good use for the additional comments after the ``---`` marker is | |
715 | for a ``diffstat``, to show what files have changed, and the number of | |
716 | inserted and deleted lines per file. A ``diffstat`` is especially useful | |
717 | on bigger patches. If you are going to include a ``diffstat`` after the | |
718 | ``---`` marker, please use ``diffstat`` options ``-p 1 -w 70`` so that | |
719 | filenames are listed from the top of the kernel source tree and don't | |
720 | use too much horizontal space (easily fit in 80 columns, maybe with some | |
721 | indentation). (``git`` generates appropriate diffstats by default.) | |
722 | ||
723 | Other comments relevant only to the moment or the maintainer, not | |
724 | suitable for the permanent changelog, should also go here. A good | |
725 | example of such comments might be ``patch changelogs`` which describe | |
726 | what has changed between the v1 and v2 version of the patch. | |
727 | ||
728 | Please put this information **after** the ``---`` line which separates | |
729 | the changelog from the rest of the patch. The version information is | |
730 | not part of the changelog which gets committed to the git tree. It is | |
731 | additional information for the reviewers. If it's placed above the | |
732 | commit tags, it needs manual interaction to remove it. If it is below | |
733 | the separator line, it gets automatically stripped off when applying the | |
734 | patch:: | |
735 | ||
736 | <commit message> | |
737 | ... | |
738 | Signed-off-by: Author <author@mail> | |
739 | --- | |
740 | V2 -> V3: Removed redundant helper function | |
741 | V1 -> V2: Cleaned up coding style and addressed review comments | |
742 | ||
743 | path/to/file | 5+++-- | |
744 | ... | |
75f8426c PJ |
745 | |
746 | See more details on the proper patch format in the following | |
747 | references. | |
748 | ||
31c9d7c8 TG |
749 | .. _backtraces: |
750 | ||
adb95582 RT |
751 | Backtraces in commit messages |
752 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
78f101a1 BP |
753 | |
754 | Backtraces help document the call chain leading to a problem. However, | |
755 | not all backtraces are helpful. For example, early boot call chains are | |
756 | unique and obvious. Copying the full dmesg output verbatim, however, | |
757 | adds distracting information like timestamps, module lists, register and | |
758 | stack dumps. | |
759 | ||
760 | Therefore, the most useful backtraces should distill the relevant | |
761 | information from the dump, which makes it easier to focus on the real | |
762 | issue. Here is an example of a well-trimmed backtrace:: | |
763 | ||
764 | unchecked MSR access error: WRMSR to 0xd51 (tried to write 0x0000000000000064) | |
765 | at rIP: 0xffffffffae059994 (native_write_msr+0x4/0x20) | |
766 | Call Trace: | |
767 | mba_wrmsr | |
768 | update_domains | |
769 | rdtgroup_mkdir | |
770 | ||
5903019b MCC |
771 | .. _explicit_in_reply_to: |
772 | ||
ef227c39 DD |
773 | Explicit In-Reply-To headers |
774 | ---------------------------- | |
d7ac8d85 CM |
775 | |
776 | It can be helpful to manually add In-Reply-To: headers to a patch | |
5903019b | 777 | (e.g., when using ``git send-email``) to associate the patch with |
d7ac8d85 CM |
778 | previous relevant discussion, e.g. to link a bug fix to the email with |
779 | the bug report. However, for a multi-patch series, it is generally | |
780 | best to avoid using In-Reply-To: to link to older versions of the | |
781 | series. This way multiple versions of the patch don't become an | |
782 | unmanageable forest of references in email clients. If a link is | |
a9d85efb | 783 | helpful, you can use the https://lore.kernel.org/ redirector (e.g., in |
d7ac8d85 CM |
784 | the cover email text) to link to an earlier version of the patch series. |
785 | ||
75f8426c | 786 | |
ef227c39 DD |
787 | Providing base tree information |
788 | ------------------------------- | |
e8686a40 KR |
789 | |
790 | When other developers receive your patches and start the review process, | |
d254d263 BPA |
791 | it is absolutely necessary for them to know what is the base |
792 | commit/branch your work applies on, considering the sheer amount of | |
793 | maintainer trees present nowadays. Note again the **T:** entry in the | |
794 | MAINTAINERS file explained above. | |
795 | ||
796 | This is even more important for automated CI processes that attempt to | |
797 | run a series of tests in order to establish the quality of your | |
798 | submission before the maintainer starts the review. | |
e8686a40 KR |
799 | |
800 | If you are using ``git format-patch`` to generate your patches, you can | |
801 | automatically include the base tree information in your submission by | |
802 | using the ``--base`` flag. The easiest and most convenient way to use | |
803 | this option is with topical branches:: | |
804 | ||
805 | $ git checkout -t -b my-topical-branch master | |
806 | Branch 'my-topical-branch' set up to track local branch 'master'. | |
807 | Switched to a new branch 'my-topical-branch' | |
808 | ||
809 | [perform your edits and commits] | |
810 | ||
811 | $ git format-patch --base=auto --cover-letter -o outgoing/ master | |
812 | outgoing/0000-cover-letter.patch | |
813 | outgoing/0001-First-Commit.patch | |
814 | outgoing/... | |
815 | ||
816 | When you open ``outgoing/0000-cover-letter.patch`` for editing, you will | |
817 | notice that it will have the ``base-commit:`` trailer at the very | |
818 | bottom, which provides the reviewer and the CI tools enough information | |
819 | to properly perform ``git am`` without worrying about conflicts:: | |
820 | ||
821 | $ git checkout -b patch-review [base-commit-id] | |
822 | Switched to a new branch 'patch-review' | |
823 | $ git am patches.mbox | |
824 | Applying: First Commit | |
825 | Applying: ... | |
826 | ||
827 | Please see ``man git-format-patch`` for more information about this | |
828 | option. | |
829 | ||
830 | .. note:: | |
831 | ||
832 | The ``--base`` feature was introduced in git version 2.9.0. | |
833 | ||
834 | If you are not using git to format your patches, you can still include | |
835 | the same ``base-commit`` trailer to indicate the commit hash of the tree | |
836 | on which your work is based. You should add it either in the cover | |
837 | letter or in the first patch of the series and it should be placed | |
838 | either below the ``---`` line or at the very bottom of all other | |
839 | content, right before your email signature. | |
840 | ||
d254d263 BPA |
841 | Make sure that base commit is in an official maintainer/mainline tree |
842 | and not in some internal, accessible only to you tree - otherwise it | |
843 | would be worthless. | |
e8686a40 | 844 | |
eb5ed2fa MB |
845 | Tooling |
846 | ------- | |
847 | ||
848 | Many of the technical aspects of this process can be automated using | |
849 | b4, documented at <https://b4.docs.kernel.org/en/latest/>. This can | |
850 | help with things like tracking dependencies, running checkpatch and | |
851 | with formatting and sending mails. | |
852 | ||
89edeedd JC |
853 | References |
854 | ---------- | |
5b0ed2c6 XVP |
855 | |
856 | Andrew Morton, "The perfect patch" (tpp). | |
e7b4311e | 857 | <https://www.ozlabs.org/~akpm/stuff/tpp.txt> |
5b0ed2c6 | 858 | |
8e9cb8fd | 859 | Jeff Garzik, "Linux kernel patch submission format". |
5aff7c46 | 860 | <https://web.archive.org/web/20180829112450/http://linux.yyz.us/patch-format.html> |
5b0ed2c6 | 861 | |
8e9cb8fd | 862 | Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". |
f5039935 | 863 | <http://www.kroah.com/log/linux/maintainer.html> |
9b2c7677 | 864 | |
f5039935 | 865 | <http://www.kroah.com/log/linux/maintainer-02.html> |
9b2c7677 | 866 | |
f5039935 | 867 | <http://www.kroah.com/log/linux/maintainer-03.html> |
9b2c7677 | 868 | |
f5039935 | 869 | <http://www.kroah.com/log/linux/maintainer-04.html> |
9b2c7677 | 870 | |
f5039935 | 871 | <http://www.kroah.com/log/linux/maintainer-05.html> |
9b2c7677 | 872 | |
7e0dae61 | 873 | <http://www.kroah.com/log/linux/maintainer-06.html> |
5b0ed2c6 | 874 | |
9912d0bb | 875 | Kernel Documentation/process/coding-style.rst |
5b0ed2c6 | 876 | |
8e9cb8fd | 877 | Linus Torvalds's mail on the canonical patch format: |
05a5f51c | 878 | <https://lore.kernel.org/r/Pine.LNX.4.58.0504071023190.28951@ppc970.osdl.org> |
9536727e AK |
879 | |
880 | Andi Kleen, "On submitting kernel patches" | |
25985edc | 881 | Some strategies to get difficult or controversial changes in. |
9b2c7677 | 882 | |
9536727e | 883 | http://halobates.de/on-submitting-patches.pdf |