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