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