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