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 Read Documentation/SubmitChecklist for a list of items to check
>> 14 before submitting code. If you are submitting a driver, also read
>> 15 Documentation/SubmittingDrivers.
>> 16
>> 17
>> 18
>> 19 --------------------------------------------
>> 20 SECTION 1 - CREATING AND SENDING YOUR CHANGE
>> 21 --------------------------------------------
>> 22
>> 23
>> 24
>> 25 1) "diff -up"
>> 26 ------------
>> 27
>> 28 Use "diff -up" or "diff -uprN" to create patches.
>> 29
>> 30 All changes to the Linux kernel occur in the form of patches, as
>> 31 generated by diff(1). When creating your patch, make sure to create it
>> 32 in "unified diff" format, as supplied by the '-u' argument to diff(1).
>> 33 Also, please use the '-p' argument which shows which C function each
>> 34 change is in - that makes the resultant diff a lot easier to read.
>> 35 Patches should be based in the root kernel source directory,
>> 36 not in any lower subdirectory.
>> 37
>> 38 To create a patch for a single file, it is often sufficient to do:
>> 39
>> 40 SRCTREE= linux-2.6
>> 41 MYFILE= drivers/net/mydriver.c
>> 42
>> 43 cd $SRCTREE
>> 44 cp $MYFILE $MYFILE.orig
>> 45 vi $MYFILE # make your change
>> 46 cd ..
>> 47 diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch
>> 48
>> 49 To create a patch for multiple files, you should unpack a "vanilla",
>> 50 or unmodified kernel source tree, and generate a diff against your
>> 51 own source tree. For example:
>> 52
>> 53 MYSRC= /devel/linux-2.6
>> 54
>> 55 tar xvfz linux-2.6.12.tar.gz
>> 56 mv linux-2.6.12 linux-2.6.12-vanilla
>> 57 diff -uprN -X linux-2.6.12-vanilla/Documentation/dontdiff \
>> 58 linux-2.6.12-vanilla $MYSRC > /tmp/patch
>> 59
>> 60 "dontdiff" is a list of files which are generated by the kernel during
>> 61 the build process, and should be ignored in any diff(1)-generated
>> 62 patch. The "dontdiff" file is included in the kernel tree in
>> 63 2.6.12 and later.
>> 64
>> 65 Make sure your patch does not include any extra files which do not
>> 66 belong in a patch submission. Make sure to review your patch -after-
>> 67 generated it with diff(1), to ensure accuracy.
>> 68
>> 69 If your changes produce a lot of deltas, you may want to look into
>> 70 splitting them into individual patches which modify things in
>> 71 logical stages. This will facilitate easier reviewing by other
>> 72 kernel developers, very important if you want your patch accepted.
>> 73 There are a number of scripts which can aid in this:
>> 74
>> 75 Quilt:
>> 76 http://savannah.nongnu.org/projects/quilt
>> 77
>> 78 Andrew Morton's patch scripts:
>> 79 http://userweb.kernel.org/~akpm/stuff/patch-scripts.tar.gz
>> 80 Instead of these scripts, quilt is the recommended patch management
>> 81 tool (see above).
>> 82
>> 83
>> 84
>> 85 2) Describe your changes.
>> 86
>> 87 Describe the technical detail of the change(s) your patch includes.
>> 88
>> 89 Be as specific as possible. The WORST descriptions possible include
>> 90 things like "update driver X", "bug fix for driver X", or "this patch
>> 91 includes updates for subsystem X. Please apply."
>> 92
>> 93 The maintainer will thank you if you write your patch description in a
>> 94 form which can be easily pulled into Linux's source code management
>> 95 system, git, as a "commit log". See #15, below.
>> 96
>> 97 If your description starts to get long, that's a sign that you probably
>> 98 need to split up your patch. See #3, next.
>> 99
>> 100 When you submit or resubmit a patch or patch series, include the
>> 101 complete patch description and justification for it. Don't just
>> 102 say that this is version N of the patch (series). Don't expect the
>> 103 patch merger to refer back to earlier patch versions or referenced
>> 104 URLs to find the patch description and put that into the patch.
>> 105 I.e., the patch (series) and its description should be self-contained.
>> 106 This benefits both the patch merger(s) and reviewers. Some reviewers
>> 107 probably didn't even receive earlier versions of the patch.
>> 108
>> 109 If the patch fixes a logged bug entry, refer to that bug entry by
>> 110 number and URL.
>> 111
>> 112
>> 113 3) Separate your changes.
>> 114
>> 115 Separate _logical changes_ into a single patch file.
>> 116
>> 117 For example, if your changes include both bug fixes and performance
>> 118 enhancements for a single driver, separate those changes into two
>> 119 or more patches. If your changes include an API update, and a new
>> 120 driver which uses that new API, separate those into two patches.
>> 121
>> 122 On the other hand, if you make a single change to numerous files,
>> 123 group those changes into a single patch. Thus a single logical change
>> 124 is contained within a single patch.
>> 125
>> 126 If one patch depends on another patch in order for a change to be
>> 127 complete, that is OK. Simply note "this patch depends on patch X"
>> 128 in your patch description.
>> 129
>> 130 If you cannot condense your patch set into a smaller set of patches,
>> 131 then only post say 15 or so at a time and wait for review and integration.
>> 132
>> 133
>> 134 If your patch fixes a bug in a specific commit, e.g. you found an issue using
>> 135 git-bisect, please use the 'Fixes:' tag with the first 12 characters of the
>> 136 SHA-1 ID, and the one line summary.
>> 137 Example:
>> 138
>> 139 Fixes: e21d2170f366 ("video: remove unnecessary platform_set_drvdata()")
>> 140
>> 141 The following git-config settings can be used to add a pretty format for
>> 142 outputting the above style in the git log or git show commands
>> 143
>> 144 [core]
>> 145 abbrev = 12
>> 146 [pretty]
>> 147 fixes = Fixes: %h (\"%s\")
>> 148
>> 149 4) Style check your changes.
>> 150
>> 151 Check your patch for basic style violations, details of which can be
>> 152 found in Documentation/CodingStyle. Failure to do so simply wastes
>> 153 the reviewers time and will get your patch rejected, probably
>> 154 without even being read.
>> 155
>> 156 At a minimum you should check your patches with the patch style
>> 157 checker prior to submission (scripts/checkpatch.pl). You should
>> 158 be able to justify all violations that remain in your patch.
>> 159
>> 160
>> 161
>> 162 5) Select e-mail destination.
>> 163
>> 164 Look through the MAINTAINERS file and the source code, and determine
>> 165 if your change applies to a specific subsystem of the kernel, with
>> 166 an assigned maintainer. If so, e-mail that person. The script
>> 167 scripts/get_maintainer.pl can be very useful at this step.
>> 168
>> 169 If no maintainer is listed, or the maintainer does not respond, send
>> 170 your patch to the primary Linux kernel developer's mailing list,
>> 171 linux-kernel@vger.kernel.org. Most kernel developers monitor this
>> 172 e-mail list, and can comment on your changes.
>> 173
>> 174
>> 175 Do not send more than 15 patches at once to the vger mailing lists!!!
>> 176
>> 177
>> 178 Linus Torvalds is the final arbiter of all changes accepted into the
>> 179 Linux kernel. His e-mail address is <torvalds@linux-foundation.org>.
>> 180 He gets a lot of e-mail, so typically you should do your best to -avoid-
>> 181 sending him e-mail.
>> 182
>> 183 Patches which are bug fixes, are "obvious" changes, or similarly
>> 184 require little discussion should be sent or CC'd to Linus. Patches
>> 185 which require discussion or do not have a clear advantage should
>> 186 usually be sent first to linux-kernel. Only after the patch is
>> 187 discussed should the patch then be submitted to Linus.
>> 188
>> 189
>> 190
>> 191 6) Select your CC (e-mail carbon copy) list.
>> 192
>> 193 Unless you have a reason NOT to do so, CC linux-kernel@vger.kernel.org.
>> 194
>> 195 Other kernel developers besides Linus need to be aware of your change,
>> 196 so that they may comment on it and offer code review and suggestions.
>> 197 linux-kernel is the primary Linux kernel developer mailing list.
>> 198 Other mailing lists are available for specific subsystems, such as
>> 199 USB, framebuffer devices, the VFS, the SCSI subsystem, etc. See the
>> 200 MAINTAINERS file for a mailing list that relates specifically to
>> 201 your change.
>> 202
>> 203 Majordomo lists of VGER.KERNEL.ORG at:
>> 204 <http://vger.kernel.org/vger-lists.html>
>> 205
>> 206 If changes affect userland-kernel interfaces, please send
>> 207 the MAN-PAGES maintainer (as listed in the MAINTAINERS file)
>> 208 a man-pages patch, or at least a notification of the change,
>> 209 so that some information makes its way into the manual pages.
>> 210
>> 211 Even if the maintainer did not respond in step #5, make sure to ALWAYS
>> 212 copy the maintainer when you change their code.
>> 213
>> 214 For small patches you may want to CC the Trivial Patch Monkey
>> 215 trivial@kernel.org which collects "trivial" patches. Have a look
>> 216 into the MAINTAINERS file for its current manager.
>> 217 Trivial patches must qualify for one of the following rules:
>> 218 Spelling fixes in documentation
>> 219 Spelling fixes which could break grep(1)
>> 220 Warning fixes (cluttering with useless warnings is bad)
>> 221 Compilation fixes (only if they are actually correct)
>> 222 Runtime fixes (only if they actually fix things)
>> 223 Removing use of deprecated functions/macros (eg. check_region)
>> 224 Contact detail and documentation fixes
>> 225 Non-portable code replaced by portable code (even in arch-specific,
>> 226 since people copy, as long as it's trivial)
>> 227 Any fix by the author/maintainer of the file (ie. patch monkey
>> 228 in re-transmission mode)
>> 229
>> 230
>> 231
>> 232 7) No MIME, no links, no compression, no attachments. Just plain text.
>> 233
>> 234 Linus and other kernel developers need to be able to read and comment
>> 235 on the changes you are submitting. It is important for a kernel
>> 236 developer to be able to "quote" your changes, using standard e-mail
>> 237 tools, so that they may comment on specific portions of your code.
>> 238
>> 239 For this reason, all patches should be submitting e-mail "inline".
>> 240 WARNING: Be wary of your editor's word-wrap corrupting your patch,
>> 241 if you choose to cut-n-paste your patch.
>> 242
>> 243 Do not attach the patch as a MIME attachment, compressed or not.
>> 244 Many popular e-mail applications will not always transmit a MIME
>> 245 attachment as plain text, making it impossible to comment on your
>> 246 code. A MIME attachment also takes Linus a bit more time to process,
>> 247 decreasing the likelihood of your MIME-attached change being accepted.
>> 248
>> 249 Exception: If your mailer is mangling patches then someone may ask
>> 250 you to re-send them using MIME.
>> 251
>> 252 See Documentation/email-clients.txt for hints about configuring
>> 253 your e-mail client so that it sends your patches untouched.
>> 254
>> 255 8) E-mail size.
>> 256
>> 257 When sending patches to Linus, always follow step #7.
>> 258
>> 259 Large changes are not appropriate for mailing lists, and some
>> 260 maintainers. If your patch, uncompressed, exceeds 300 kB in size,
>> 261 it is preferred that you store your patch on an Internet-accessible
>> 262 server, and provide instead a URL (link) pointing to your patch.
>> 263
>> 264
>> 265
>> 266 9) Name your kernel version.
>> 267
>> 268 It is important to note, either in the subject line or in the patch
>> 269 description, the kernel version to which this patch applies.
>> 270
>> 271 If the patch does not apply cleanly to the latest kernel version,
>> 272 Linus will not apply it.
>> 273
>> 274
>> 275
>> 276 10) Don't get discouraged. Re-submit.
>> 277
>> 278 After you have submitted your change, be patient and wait. If Linus
>> 279 likes your change and applies it, it will appear in the next version
>> 280 of the kernel that he releases.
>> 281
>> 282 However, if your change doesn't appear in the next version of the
>> 283 kernel, there could be any number of reasons. It's YOUR job to
>> 284 narrow down those reasons, correct what was wrong, and submit your
>> 285 updated change.
>> 286
>> 287 It is quite common for Linus to "drop" your patch without comment.
>> 288 That's the nature of the system. If he drops your patch, it could be
>> 289 due to
>> 290 * Your patch did not apply cleanly to the latest kernel version.
>> 291 * Your patch was not sufficiently discussed on linux-kernel.
>> 292 * A style issue (see section 2).
>> 293 * An e-mail formatting issue (re-read this section).
>> 294 * A technical problem with your change.
>> 295 * He gets tons of e-mail, and yours got lost in the shuffle.
>> 296 * You are being annoying.
>> 297
>> 298 When in doubt, solicit comments on linux-kernel mailing list.
>> 299
>> 300
>> 301
>> 302 11) Include PATCH in the subject
>> 303
>> 304 Due to high e-mail traffic to Linus, and to linux-kernel, it is common
>> 305 convention to prefix your subject line with [PATCH]. This lets Linus
>> 306 and other kernel developers more easily distinguish patches from other
>> 307 e-mail discussions.
>> 308
>> 309
>> 310
>> 311 12) Sign your work
>> 312
>> 313 To improve tracking of who did what, especially with patches that can
>> 314 percolate to their final resting place in the kernel through several
>> 315 layers of maintainers, we've introduced a "sign-off" procedure on
>> 316 patches that are being emailed around.
>> 317
>> 318 The sign-off is a simple line at the end of the explanation for the
>> 319 patch, which certifies that you wrote it or otherwise have the right to
>> 320 pass it on as an open-source patch. The rules are pretty simple: if you
>> 321 can certify the below:
>> 322
>> 323 Developer's Certificate of Origin 1.1
>> 324
>> 325 By making a contribution to this project, I certify that:
>> 326
>> 327 (a) The contribution was created in whole or in part by me and I
>> 328 have the right to submit it under the open source license
>> 329 indicated in the file; or
>> 330
>> 331 (b) The contribution is based upon previous work that, to the best
>> 332 of my knowledge, is covered under an appropriate open source
>> 333 license and I have the right under that license to submit that
>> 334 work with modifications, whether created in whole or in part
>> 335 by me, under the same open source license (unless I am
>> 336 permitted to submit under a different license), as indicated
>> 337 in the file; or
>> 338
>> 339 (c) The contribution was provided directly to me by some other
>> 340 person who certified (a), (b) or (c) and I have not modified
>> 341 it.
>> 342
>> 343 (d) I understand and agree that this project and the contribution
>> 344 are public and that a record of the contribution (including all
>> 345 personal information I submit with it, including my sign-off) is
>> 346 maintained indefinitely and may be redistributed consistent with
>> 347 this project or the open source license(s) involved.
>> 348
>> 349 then you just add a line saying
>> 350
>> 351 Signed-off-by: Random J Developer <random@developer.example.org>
>> 352
>> 353 using your real name (sorry, no pseudonyms or anonymous contributions.)
>> 354
>> 355 Some people also put extra tags at the end. They'll just be ignored for
>> 356 now, but you can do this to mark internal company procedures or just
>> 357 point out some special detail about the sign-off.
>> 358
>> 359 If you are a subsystem or branch maintainer, sometimes you need to slightly
>> 360 modify patches you receive in order to merge them, because the code is not
>> 361 exactly the same in your tree and the submitters'. If you stick strictly to
>> 362 rule (c), you should ask the submitter to rediff, but this is a totally
>> 363 counter-productive waste of time and energy. Rule (b) allows you to adjust
>> 364 the code, but then it is very impolite to change one submitter's code and
>> 365 make him endorse your bugs. To solve this problem, it is recommended that
>> 366 you add a line between the last Signed-off-by header and yours, indicating
>> 367 the nature of your changes. While there is nothing mandatory about this, it
>> 368 seems like prepending the description with your mail and/or name, all
>> 369 enclosed in square brackets, is noticeable enough to make it obvious that
>> 370 you are responsible for last-minute changes. Example :
>> 371
>> 372 Signed-off-by: Random J Developer <random@developer.example.org>
>> 373 [lucky@maintainer.example.org: struct foo moved from foo.c to foo.h]
>> 374 Signed-off-by: Lucky K Maintainer <lucky@maintainer.example.org>
>> 375
>> 376 This practise is particularly helpful if you maintain a stable branch and
>> 377 want at the same time to credit the author, track changes, merge the fix,
>> 378 and protect the submitter from complaints. Note that under no circumstances
>> 379 can you change the author's identity (the From header), as it is the one
>> 380 which appears in the changelog.
>> 381
>> 382 Special note to back-porters: It seems to be a common and useful practise
>> 383 to insert an indication of the origin of a patch at the top of the commit
>> 384 message (just after the subject line) to facilitate tracking. For instance,
>> 385 here's what we see in 2.6-stable :
>> 386
>> 387 Date: Tue May 13 19:10:30 2008 +0000
>> 388
>> 389 SCSI: libiscsi regression in 2.6.25: fix nop timer handling
>> 390
>> 391 commit 4cf1043593db6a337f10e006c23c69e5fc93e722 upstream
>> 392
>> 393 And here's what appears in 2.4 :
>> 394
>> 395 Date: Tue May 13 22:12:27 2008 +0200
>> 396
>> 397 wireless, airo: waitbusy() won't delay
>> 398
>> 399 [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a]
>> 400
>> 401 Whatever the format, this information provides a valuable help to people
>> 402 tracking your trees, and to people trying to trouble-shoot bugs in your
>> 403 tree.
>> 404
>> 405
>> 406 13) When to use Acked-by: and Cc:
>> 407
>> 408 The Signed-off-by: tag indicates that the signer was involved in the
>> 409 development of the patch, or that he/she was in the patch's delivery path.
>> 410
>> 411 If a person was not directly involved in the preparation or handling of a
>> 412 patch but wishes to signify and record their approval of it then they can
>> 413 arrange to have an Acked-by: line added to the patch's changelog.
>> 414
>> 415 Acked-by: is often used by the maintainer of the affected code when that
>> 416 maintainer neither contributed to nor forwarded the patch.
>> 417
>> 418 Acked-by: is not as formal as Signed-off-by:. It is a record that the acker
>> 419 has at least reviewed the patch and has indicated acceptance. Hence patch
>> 420 mergers will sometimes manually convert an acker's "yep, looks good to me"
>> 421 into an Acked-by:.
>> 422
>> 423 Acked-by: does not necessarily indicate acknowledgement of the entire patch.
>> 424 For example, if a patch affects multiple subsystems and has an Acked-by: from
>> 425 one subsystem maintainer then this usually indicates acknowledgement of just
>> 426 the part which affects that maintainer's code. Judgement should be used here.
>> 427 When in doubt people should refer to the original discussion in the mailing
>> 428 list archives.
>> 429
>> 430 If a person has had the opportunity to comment on a patch, but has not
>> 431 provided such comments, you may optionally add a "Cc:" tag to the patch.
>> 432 This is the only tag which might be added without an explicit action by the
>> 433 person it names. This tag documents that potentially interested parties
>> 434 have been included in the discussion
>> 435
>> 436
>> 437 14) Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes:
>> 438
>> 439 If this patch fixes a problem reported by somebody else, consider adding a
>> 440 Reported-by: tag to credit the reporter for their contribution. Please
>> 441 note that this tag should not be added without the reporter's permission,
>> 442 especially if the problem was not reported in a public forum. That said,
>> 443 if we diligently credit our bug reporters, they will, hopefully, be
>> 444 inspired to help us again in the future.
>> 445
>> 446 A Tested-by: tag indicates that the patch has been successfully tested (in
>> 447 some environment) by the person named. This tag informs maintainers that
>> 448 some testing has been performed, provides a means to locate testers for
>> 449 future patches, and ensures credit for the testers.
>> 450
>> 451 Reviewed-by:, instead, indicates that the patch has been reviewed and found
>> 452 acceptable according to the Reviewer's Statement:
>> 453
>> 454 Reviewer's statement of oversight
>> 455
>> 456 By offering my Reviewed-by: tag, I state that:
>> 457
>> 458 (a) I have carried out a technical review of this patch to
>> 459 evaluate its appropriateness and readiness for inclusion into
>> 460 the mainline kernel.
>> 461
>> 462 (b) Any problems, concerns, or questions relating to the patch
>> 463 have been communicated back to the submitter. I am satisfied
>> 464 with the submitter's response to my comments.
>> 465
>> 466 (c) While there may be things that could be improved with this
>> 467 submission, I believe that it is, at this time, (1) a
>> 468 worthwhile modification to the kernel, and (2) free of known
>> 469 issues which would argue against its inclusion.
>> 470
>> 471 (d) While I have reviewed the patch and believe it to be sound, I
>> 472 do not (unless explicitly stated elsewhere) make any
>> 473 warranties or guarantees that it will achieve its stated
>> 474 purpose or function properly in any given situation.
>> 475
>> 476 A Reviewed-by tag is a statement of opinion that the patch is an
>> 477 appropriate modification of the kernel without any remaining serious
>> 478 technical issues. Any interested reviewer (who has done the work) can
>> 479 offer a Reviewed-by tag for a patch. This tag serves to give credit to
>> 480 reviewers and to inform maintainers of the degree of review which has been
>> 481 done on the patch. Reviewed-by: tags, when supplied by reviewers known to
>> 482 understand the subject area and to perform thorough reviews, will normally
>> 483 increase the likelihood of your patch getting into the kernel.
>> 484
>> 485 A Suggested-by: tag indicates that the patch idea is suggested by the person
>> 486 named and ensures credit to the person for the idea. Please note that this
>> 487 tag should not be added without the reporter's permission, especially if the
>> 488 idea was not posted in a public forum. That said, if we diligently credit our
>> 489 idea reporters, they will, hopefully, be inspired to help us again in the
>> 490 future.
>> 491
>> 492 A Fixes: tag indicates that the patch fixes an issue in a previous commit. It
>> 493 is used to make it easy to determine where a bug originated, which can help
>> 494 review a bug fix. This tag also assists the stable kernel team in determining
>> 495 which stable kernel versions should receive your fix. This is the preferred
>> 496 method for indicating a bug fixed by the patch. See #2 above for more details.
>> 497
>> 498
>> 499 15) The canonical patch format
>> 500
>> 501 The canonical patch subject line is:
>> 502
>> 503 Subject: [PATCH 001/123] subsystem: summary phrase
>> 504
>> 505 The canonical patch message body contains the following:
>> 506
>> 507 - A "from" line specifying the patch author.
>> 508
>> 509 - An empty line.
>> 510
>> 511 - The body of the explanation, which will be copied to the
>> 512 permanent changelog to describe this patch.
>> 513
>> 514 - The "Signed-off-by:" lines, described above, which will
>> 515 also go in the changelog.
>> 516
>> 517 - A marker line containing simply "---".
>> 518
>> 519 - Any additional comments not suitable for the changelog.
>> 520
>> 521 - The actual patch (diff output).
>> 522
>> 523 The Subject line format makes it very easy to sort the emails
>> 524 alphabetically by subject line - pretty much any email reader will
>> 525 support that - since because the sequence number is zero-padded,
>> 526 the numerical and alphabetic sort is the same.
>> 527
>> 528 The "subsystem" in the email's Subject should identify which
>> 529 area or subsystem of the kernel is being patched.
>> 530
>> 531 The "summary phrase" in the email's Subject should concisely
>> 532 describe the patch which that email contains. The "summary
>> 533 phrase" should not be a filename. Do not use the same "summary
>> 534 phrase" for every patch in a whole patch series (where a "patch
>> 535 series" is an ordered sequence of multiple, related patches).
>> 536
>> 537 Bear in mind that the "summary phrase" of your email becomes a
>> 538 globally-unique identifier for that patch. It propagates all the way
>> 539 into the git changelog. The "summary phrase" may later be used in
>> 540 developer discussions which refer to the patch. People will want to
>> 541 google for the "summary phrase" to read discussion regarding that
>> 542 patch. It will also be the only thing that people may quickly see
>> 543 when, two or three months later, they are going through perhaps
>> 544 thousands of patches using tools such as "gitk" or "git log
>> 545 --oneline".
>> 546
>> 547 For these reasons, the "summary" must be no more than 70-75
>> 548 characters, and it must describe both what the patch changes, as well
>> 549 as why the patch might be necessary. It is challenging to be both
>> 550 succinct and descriptive, but that is what a well-written summary
>> 551 should do.
>> 552
>> 553 The "summary phrase" may be prefixed by tags enclosed in square
>> 554 brackets: "Subject: [PATCH tag] <summary phrase>". The tags are not
>> 555 considered part of the summary phrase, but describe how the patch
>> 556 should be treated. Common tags might include a version descriptor if
>> 557 the multiple versions of the patch have been sent out in response to
>> 558 comments (i.e., "v1, v2, v3"), or "RFC" to indicate a request for
>> 559 comments. If there are four patches in a patch series the individual
>> 560 patches may be numbered like this: 1/4, 2/4, 3/4, 4/4. This assures
>> 561 that developers understand the order in which the patches should be
>> 562 applied and that they have reviewed or applied all of the patches in
>> 563 the patch series.
>> 564
>> 565 A couple of example Subjects:
>> 566
>> 567 Subject: [patch 2/5] ext2: improve scalability of bitmap searching
>> 568 Subject: [PATCHv2 001/207] x86: fix eflags tracking
>> 569
>> 570 The "from" line must be the very first line in the message body,
>> 571 and has the form:
>> 572
>> 573 From: Original Author <author@example.com>
>> 574
>> 575 The "from" line specifies who will be credited as the author of the
>> 576 patch in the permanent changelog. If the "from" line is missing,
>> 577 then the "From:" line from the email header will be used to determine
>> 578 the patch author in the changelog.
>> 579
>> 580 The explanation body will be committed to the permanent source
>> 581 changelog, so should make sense to a competent reader who has long
>> 582 since forgotten the immediate details of the discussion that might
>> 583 have led to this patch. Including symptoms of the failure which the
>> 584 patch addresses (kernel log messages, oops messages, etc.) is
>> 585 especially useful for people who might be searching the commit logs
>> 586 looking for the applicable patch. If a patch fixes a compile failure,
>> 587 it may not be necessary to include _all_ of the compile failures; just
>> 588 enough that it is likely that someone searching for the patch can find
>> 589 it. As in the "summary phrase", it is important to be both succinct as
>> 590 well as descriptive.
>> 591
>> 592 The "---" marker line serves the essential purpose of marking for patch
>> 593 handling tools where the changelog message ends.
>> 594
>> 595 One good use for the additional comments after the "---" marker is for
>> 596 a diffstat, to show what files have changed, and the number of
>> 597 inserted and deleted lines per file. A diffstat is especially useful
>> 598 on bigger patches. Other comments relevant only to the moment or the
>> 599 maintainer, not suitable for the permanent changelog, should also go
>> 600 here. A good example of such comments might be "patch changelogs"
>> 601 which describe what has changed between the v1 and v2 version of the
>> 602 patch.
>> 603
>> 604 If you are going to include a diffstat after the "---" marker, please
>> 605 use diffstat options "-p 1 -w 70" so that filenames are listed from
>> 606 the top of the kernel source tree and don't use too much horizontal
>> 607 space (easily fit in 80 columns, maybe with some indentation).
>> 608
>> 609 See more details on the proper patch format in the following
>> 610 references.
>> 611
>> 612
>> 613 16) Sending "git pull" requests (from Linus emails)
>> 614
>> 615 Please write the git repo address and branch name alone on the same line
>> 616 so that I can't even by mistake pull from the wrong branch, and so
>> 617 that a triple-click just selects the whole thing.
>> 618
>> 619 So the proper format is something along the lines of:
>> 620
>> 621 "Please pull from
>> 622
>> 623 git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus
>> 624
>> 625 to get these changes:"
>> 626
>> 627 so that I don't have to hunt-and-peck for the address and inevitably
>> 628 get it wrong (actually, I've only gotten it wrong a few times, and
>> 629 checking against the diffstat tells me when I get it wrong, but I'm
>> 630 just a lot more comfortable when I don't have to "look for" the right
>> 631 thing to pull, and double-check that I have the right branch-name).
>> 632
>> 633
>> 634 Please use "git diff -M --stat --summary" to generate the diffstat:
>> 635 the -M enables rename detection, and the summary enables a summary of
>> 636 new/deleted or renamed files.
>> 637
>> 638 With rename detection, the statistics are rather different [...]
>> 639 because git will notice that a fair number of the changes are renames.
>> 640
>> 641 -----------------------------------
>> 642 SECTION 2 - HINTS, TIPS, AND TRICKS
>> 643 -----------------------------------
>> 644
>> 645 This section lists many of the common "rules" associated with code
>> 646 submitted to the kernel. There are always exceptions... but you must
>> 647 have a really good reason for doing so. You could probably call this
>> 648 section Linus Computer Science 101.
>> 649
>> 650
>> 651
>> 652 1) Read Documentation/CodingStyle
>> 653
>> 654 Nuff said. If your code deviates too much from this, it is likely
>> 655 to be rejected without further review, and without comment.
>> 656
>> 657 One significant exception is when moving code from one file to
>> 658 another -- in this case you should not modify the moved code at all in
>> 659 the same patch which moves it. This clearly delineates the act of
>> 660 moving the code and your changes. This greatly aids review of the
>> 661 actual differences and allows tools to better track the history of
>> 662 the code itself.
>> 663
>> 664 Check your patches with the patch style checker prior to submission
>> 665 (scripts/checkpatch.pl). The style checker should be viewed as
>> 666 a guide not as the final word. If your code looks better with
>> 667 a violation then its probably best left alone.
>> 668
>> 669 The checker reports at three levels:
>> 670 - ERROR: things that are very likely to be wrong
>> 671 - WARNING: things requiring careful review
>> 672 - CHECK: things requiring thought
>> 673
>> 674 You should be able to justify all violations that remain in your
>> 675 patch.
>> 676
>> 677
>> 678
>> 679 2) #ifdefs are ugly
>> 680
>> 681 Code cluttered with ifdefs is difficult to read and maintain. Don't do
>> 682 it. Instead, put your ifdefs in a header, and conditionally define
>> 683 'static inline' functions, or macros, which are used in the code.
>> 684 Let the compiler optimize away the "no-op" case.
>> 685
>> 686 Simple example, of poor code:
>> 687
>> 688 dev = alloc_etherdev (sizeof(struct funky_private));
>> 689 if (!dev)
>> 690 return -ENODEV;
>> 691 #ifdef CONFIG_NET_FUNKINESS
>> 692 init_funky_net(dev);
>> 693 #endif
>> 694
>> 695 Cleaned-up example:
>> 696
>> 697 (in header)
>> 698 #ifndef CONFIG_NET_FUNKINESS
>> 699 static inline void init_funky_net (struct net_device *d) {}
>> 700 #endif
>> 701
>> 702 (in the code itself)
>> 703 dev = alloc_etherdev (sizeof(struct funky_private));
>> 704 if (!dev)
>> 705 return -ENODEV;
>> 706 init_funky_net(dev);
>> 707
>> 708
>> 709
>> 710 3) 'static inline' is better than a macro
>> 711
>> 712 Static inline functions are greatly preferred over macros.
>> 713 They provide type safety, have no length limitations, no formatting
>> 714 limitations, and under gcc they are as cheap as macros.
>> 715
>> 716 Macros should only be used for cases where a static inline is clearly
>> 717 suboptimal [there are a few, isolated cases of this in fast paths],
>> 718 or where it is impossible to use a static inline function [such as
>> 719 string-izing].
>> 720
>> 721 'static inline' is preferred over 'static __inline__', 'extern inline',
>> 722 and 'extern __inline__'.
>> 723
>> 724
>> 725
>> 726 4) Don't over-design.
>> 727
>> 728 Don't try to anticipate nebulous future cases which may or may not
>> 729 be useful: "Make it as simple as you can, and no simpler."
>> 730
>> 731
>> 732
>> 733 ----------------------
>> 734 SECTION 3 - REFERENCES
>> 735 ----------------------
>> 736
>> 737 Andrew Morton, "The perfect patch" (tpp).
>> 738 <http://userweb.kernel.org/~akpm/stuff/tpp.txt>
>> 739
>> 740 Jeff Garzik, "Linux kernel patch submission format".
>> 741 <http://linux.yyz.us/patch-format.html>
>> 742
>> 743 Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer".
>> 744 <http://www.kroah.com/log/linux/maintainer.html>
>> 745 <http://www.kroah.com/log/linux/maintainer-02.html>
>> 746 <http://www.kroah.com/log/linux/maintainer-03.html>
>> 747 <http://www.kroah.com/log/linux/maintainer-04.html>
>> 748 <http://www.kroah.com/log/linux/maintainer-05.html>
>> 749
>> 750 NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people!
>> 751 <http://marc.theaimsgroup.com/?l=linux-kernel&m=112112749912944&w=2>
>> 752
>> 753 Kernel Documentation/CodingStyle:
>> 754 <http://users.sosdg.org/~qiyong/lxr/source/Documentation/CodingStyle>
>> 755
>> 756 Linus Torvalds's mail on the canonical patch format:
>> 757 <http://lkml.org/lkml/2005/4/7/183>
>> 758
>> 759 Andi Kleen, "On submitting kernel patches"
>> 760 Some strategies to get difficult or controversial changes in.
>> 761 http://halobates.de/on-submitting-patches.pdf
>> 762
>> 763 --
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.