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