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