1 I don't have specific submission guidelines for Syslinux, but the ones 2 that appropriate to the Linux kernel are certainly good enough for 3 Syslinux. 4 5 In particular, however, I appreciate if patches sent follow the 6 standard Linux submission format, as I can automatically import them 7 into git, retaining description and author information. Thus, this 8 file from the Linux kernel might be useful. 9 10 11 ----------------------------------------------------------------------- 12 13 14 15 How to Get Your Change Into the Linux Kernel 16 or 17 Care And Operation Of Your Linus Torvalds 18 19 20 21 For a person or company who wishes to submit a change to the Linux 22 kernel, the process can sometimes be daunting if you're not familiar 23 with "the system." This text is a collection of suggestions which 24 can greatly increase the chances of your change being accepted. 25 26 Read Documentation/SubmitChecklist for a list of items to check 27 before submitting code. If you are submitting a driver, also read 28 Documentation/SubmittingDrivers. 29 30 31 32 -------------------------------------------- 33 SECTION 1 - CREATING AND SENDING YOUR CHANGE 34 -------------------------------------------- 35 36 37 38 1) "diff -up" 39 ------------ 40 41 Use "diff -up" or "diff -uprN" to create patches. 42 43 All changes to the Linux kernel occur in the form of patches, as 44 generated by diff(1). When creating your patch, make sure to create it 45 in "unified diff" format, as supplied by the '-u' argument to diff(1). 46 Also, please use the '-p' argument which shows which C function each 47 change is in - that makes the resultant diff a lot easier to read. 48 Patches should be based in the root kernel source directory, 49 not in any lower subdirectory. 50 51 To create a patch for a single file, it is often sufficient to do: 52 53 SRCTREE= linux-2.6 54 MYFILE= drivers/net/mydriver.c 55 56 cd $SRCTREE 57 cp $MYFILE $MYFILE.orig 58 vi $MYFILE # make your change 59 cd .. 60 diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch 61 62 To create a patch for multiple files, you should unpack a "vanilla", 63 or unmodified kernel source tree, and generate a diff against your 64 own source tree. For example: 65 66 MYSRC= /devel/linux-2.6 67 68 tar xvfz linux-2.6.12.tar.gz 69 mv linux-2.6.12 linux-2.6.12-vanilla 70 diff -uprN -X linux-2.6.12-vanilla/Documentation/dontdiff \ 71 linux-2.6.12-vanilla $MYSRC > /tmp/patch 72 73 "dontdiff" is a list of files which are generated by the kernel during 74 the build process, and should be ignored in any diff(1)-generated 75 patch. The "dontdiff" file is included in the kernel tree in 76 2.6.12 and later. For earlier kernel versions, you can get it 77 from <http://www.xenotime.net/linux/doc/dontdiff>. 78 79 Make sure your patch does not include any extra files which do not 80 belong in a patch submission. Make sure to review your patch -after- 81 generated it with diff(1), to ensure accuracy. 82 83 If your changes produce a lot of deltas, you may want to look into 84 splitting them into individual patches which modify things in 85 logical stages. This will facilitate easier reviewing by other 86 kernel developers, very important if you want your patch accepted. 87 There are a number of scripts which can aid in this: 88 89 Quilt: 90 http://savannah.nongnu.org/projects/quilt 91 92 Andrew Morton's patch scripts: 93 http://www.zip.com.au/~akpm/linux/patches/ 94 Instead of these scripts, quilt is the recommended patch management 95 tool (see above). 96 97 98 99 2) Describe your changes. 100 101 Describe the technical detail of the change(s) your patch includes. 102 103 Be as specific as possible. The WORST descriptions possible include 104 things like "update driver X", "bug fix for driver X", or "this patch 105 includes updates for subsystem X. Please apply." 106 107 If your description starts to get long, that's a sign that you probably 108 need to split up your patch. See #3, next. 109 110 111 112 3) Separate your changes. 113 114 Separate _logical changes_ into a single patch file. 115 116 For example, if your changes include both bug fixes and performance 117 enhancements for a single driver, separate those changes into two 118 or more patches. If your changes include an API update, and a new 119 driver which uses that new API, separate those into two patches. 120 121 On the other hand, if you make a single change to numerous files, 122 group those changes into a single patch. Thus a single logical change 123 is contained within a single patch. 124 125 If one patch depends on another patch in order for a change to be 126 complete, that is OK. Simply note "this patch depends on patch X" 127 in your patch description. 128 129 If you cannot condense your patch set into a smaller set of patches, 130 then only post say 15 or so at a time and wait for review and integration. 131 132 133 134 4) Style check your changes. 135 136 Check your patch for basic style violations, details of which can be 137 found in Documentation/CodingStyle. Failure to do so simply wastes 138 the reviewers time and will get your patch rejected, probably 139 without even being read. 140 141 At a minimum you should check your patches with the patch style 142 checker prior to submission (scripts/checkpatch.pl). You should 143 be able to justify all violations that remain in your patch. 144 145 146 147 5) Select e-mail destination. 148 149 Look through the MAINTAINERS file and the source code, and determine 150 if your change applies to a specific subsystem of the kernel, with 151 an assigned maintainer. If so, e-mail that person. 152 153 If no maintainer is listed, or the maintainer does not respond, send 154 your patch to the primary Linux kernel developer's mailing list, 155 linux-kernel (a] vger.kernel.org. Most kernel developers monitor this 156 e-mail list, and can comment on your changes. 157 158 159 Do not send more than 15 patches at once to the vger mailing lists!!! 160 161 162 Linus Torvalds is the final arbiter of all changes accepted into the 163 Linux kernel. His e-mail address is <torvalds (a] linux-foundation.org>. 164 He gets a lot of e-mail, so typically you should do your best to -avoid- 165 sending him e-mail. 166 167 Patches which are bug fixes, are "obvious" changes, or similarly 168 require little discussion should be sent or CC'd to Linus. Patches 169 which require discussion or do not have a clear advantage should 170 usually be sent first to linux-kernel. Only after the patch is 171 discussed should the patch then be submitted to Linus. 172 173 174 175 6) Select your CC (e-mail carbon copy) list. 176 177 Unless you have a reason NOT to do so, CC linux-kernel (a] vger.kernel.org. 178 179 Other kernel developers besides Linus need to be aware of your change, 180 so that they may comment on it and offer code review and suggestions. 181 linux-kernel is the primary Linux kernel developer mailing list. 182 Other mailing lists are available for specific subsystems, such as 183 USB, framebuffer devices, the VFS, the SCSI subsystem, etc. See the 184 MAINTAINERS file for a mailing list that relates specifically to 185 your change. 186 187 Majordomo lists of VGER.KERNEL.ORG at: 188 <http://vger.kernel.org/vger-lists.html> 189 190 If changes affect userland-kernel interfaces, please send 191 the MAN-PAGES maintainer (as listed in the MAINTAINERS file) 192 a man-pages patch, or at least a notification of the change, 193 so that some information makes its way into the manual pages. 194 195 Even if the maintainer did not respond in step #4, make sure to ALWAYS 196 copy the maintainer when you change their code. 197 198 For small patches you may want to CC the Trivial Patch Monkey 199 trivial (a] kernel.org managed by Adrian Bunk; which collects "trivial" 200 patches. Trivial patches must qualify for one of the following rules: 201 Spelling fixes in documentation 202 Spelling fixes which could break grep(1) 203 Warning fixes (cluttering with useless warnings is bad) 204 Compilation fixes (only if they are actually correct) 205 Runtime fixes (only if they actually fix things) 206 Removing use of deprecated functions/macros (eg. check_region) 207 Contact detail and documentation fixes 208 Non-portable code replaced by portable code (even in arch-specific, 209 since people copy, as long as it's trivial) 210 Any fix by the author/maintainer of the file (ie. patch monkey 211 in re-transmission mode) 212 URL: <http://www.kernel.org/pub/linux/kernel/people/bunk/trivial/> 213 214 215 216 7) No MIME, no links, no compression, no attachments. Just plain text. 217 218 Linus and other kernel developers need to be able to read and comment 219 on the changes you are submitting. It is important for a kernel 220 developer to be able to "quote" your changes, using standard e-mail 221 tools, so that they may comment on specific portions of your code. 222 223 For this reason, all patches should be submitting e-mail "inline". 224 WARNING: Be wary of your editor's word-wrap corrupting your patch, 225 if you choose to cut-n-paste your patch. 226 227 Do not attach the patch as a MIME attachment, compressed or not. 228 Many popular e-mail applications will not always transmit a MIME 229 attachment as plain text, making it impossible to comment on your 230 code. A MIME attachment also takes Linus a bit more time to process, 231 decreasing the likelihood of your MIME-attached change being accepted. 232 233 Exception: If your mailer is mangling patches then someone may ask 234 you to re-send them using MIME. 235 236 See Documentation/email-clients.txt for hints about configuring 237 your e-mail client so that it sends your patches untouched. 238 239 8) E-mail size. 240 241 When sending patches to Linus, always follow step #7. 242 243 Large changes are not appropriate for mailing lists, and some 244 maintainers. If your patch, uncompressed, exceeds 40 kB in size, 245 it is preferred that you store your patch on an Internet-accessible 246 server, and provide instead a URL (link) pointing to your patch. 247 248 249 250 9) Name your kernel version. 251 252 It is important to note, either in the subject line or in the patch 253 description, the kernel version to which this patch applies. 254 255 If the patch does not apply cleanly to the latest kernel version, 256 Linus will not apply it. 257 258 259 260 10) Don't get discouraged. Re-submit. 261 262 After you have submitted your change, be patient and wait. If Linus 263 likes your change and applies it, it will appear in the next version 264 of the kernel that he releases. 265 266 However, if your change doesn't appear in the next version of the 267 kernel, there could be any number of reasons. It's YOUR job to 268 narrow down those reasons, correct what was wrong, and submit your 269 updated change. 270 271 It is quite common for Linus to "drop" your patch without comment. 272 That's the nature of the system. If he drops your patch, it could be 273 due to 274 * Your patch did not apply cleanly to the latest kernel version. 275 * Your patch was not sufficiently discussed on linux-kernel. 276 * A style issue (see section 2). 277 * An e-mail formatting issue (re-read this section). 278 * A technical problem with your change. 279 * He gets tons of e-mail, and yours got lost in the shuffle. 280 * You are being annoying. 281 282 When in doubt, solicit comments on linux-kernel mailing list. 283 284 285 286 11) Include PATCH in the subject 287 288 Due to high e-mail traffic to Linus, and to linux-kernel, it is common 289 convention to prefix your subject line with [PATCH]. This lets Linus 290 and other kernel developers more easily distinguish patches from other 291 e-mail discussions. 292 293 294 295 12) Sign your work 296 297 To improve tracking of who did what, especially with patches that can 298 percolate to their final resting place in the kernel through several 299 layers of maintainers, we've introduced a "sign-off" procedure on 300 patches that are being emailed around. 301 302 The sign-off is a simple line at the end of the explanation for the 303 patch, which certifies that you wrote it or otherwise have the right to 304 pass it on as a open-source patch. The rules are pretty simple: if you 305 can certify the below: 306 307 Developer's Certificate of Origin 1.1 308 309 By making a contribution to this project, I certify that: 310 311 (a) The contribution was created in whole or in part by me and I 312 have the right to submit it under the open source license 313 indicated in the file; or 314 315 (b) The contribution is based upon previous work that, to the best 316 of my knowledge, is covered under an appropriate open source 317 license and I have the right under that license to submit that 318 work with modifications, whether created in whole or in part 319 by me, under the same open source license (unless I am 320 permitted to submit under a different license), as indicated 321 in the file; or 322 323 (c) The contribution was provided directly to me by some other 324 person who certified (a), (b) or (c) and I have not modified 325 it. 326 327 (d) I understand and agree that this project and the contribution 328 are public and that a record of the contribution (including all 329 personal information I submit with it, including my sign-off) is 330 maintained indefinitely and may be redistributed consistent with 331 this project or the open source license(s) involved. 332 333 then you just add a line saying 334 335 Signed-off-by: Random J Developer <random (a] developer.example.org> 336 337 using your real name (sorry, no pseudonyms or anonymous contributions.) 338 339 Some people also put extra tags at the end. They'll just be ignored for 340 now, but you can do this to mark internal company procedures or just 341 point out some special detail about the sign-off. 342 343 344 13) When to use Acked-by: 345 346 The Signed-off-by: tag indicates that the signer was involved in the 347 development of the patch, or that he/she was in the patch's delivery path. 348 349 If a person was not directly involved in the preparation or handling of a 350 patch but wishes to signify and record their approval of it then they can 351 arrange to have an Acked-by: line added to the patch's changelog. 352 353 Acked-by: is often used by the maintainer of the affected code when that 354 maintainer neither contributed to nor forwarded the patch. 355 356 Acked-by: is not as formal as Signed-off-by:. It is a record that the acker 357 has at least reviewed the patch and has indicated acceptance. Hence patch 358 mergers will sometimes manually convert an acker's "yep, looks good to me" 359 into an Acked-by:. 360 361 Acked-by: does not necessarily indicate acknowledgement of the entire patch. 362 For example, if a patch affects multiple subsystems and has an Acked-by: from 363 one subsystem maintainer then this usually indicates acknowledgement of just 364 the part which affects that maintainer's code. Judgement should be used here. 365 When in doubt people should refer to the original discussion in the mailing 366 list archives. 367 368 369 14) The canonical patch format 370 371 The canonical patch subject line is: 372 373 Subject: [PATCH 001/123] subsystem: summary phrase 374 375 The canonical patch message body contains the following: 376 377 - A "from" line specifying the patch author. 378 379 - An empty line. 380 381 - The body of the explanation, which will be copied to the 382 permanent changelog to describe this patch. 383 384 - The "Signed-off-by:" lines, described above, which will 385 also go in the changelog. 386 387 - A marker line containing simply "---". 388 389 - Any additional comments not suitable for the changelog. 390 391 - The actual patch (diff output). 392 393 The Subject line format makes it very easy to sort the emails 394 alphabetically by subject line - pretty much any email reader will 395 support that - since because the sequence number is zero-padded, 396 the numerical and alphabetic sort is the same. 397 398 The "subsystem" in the email's Subject should identify which 399 area or subsystem of the kernel is being patched. 400 401 The "summary phrase" in the email's Subject should concisely 402 describe the patch which that email contains. The "summary 403 phrase" should not be a filename. Do not use the same "summary 404 phrase" for every patch in a whole patch series (where a "patch 405 series" is an ordered sequence of multiple, related patches). 406 407 Bear in mind that the "summary phrase" of your email becomes 408 a globally-unique identifier for that patch. It propagates 409 all the way into the git changelog. The "summary phrase" may 410 later be used in developer discussions which refer to the patch. 411 People will want to google for the "summary phrase" to read 412 discussion regarding that patch. 413 414 A couple of example Subjects: 415 416 Subject: [patch 2/5] ext2: improve scalability of bitmap searching 417 Subject: [PATCHv2 001/207] x86: fix eflags tracking 418 419 The "from" line must be the very first line in the message body, 420 and has the form: 421 422 From: Original Author <author (a] example.com> 423 424 The "from" line specifies who will be credited as the author of the 425 patch in the permanent changelog. If the "from" line is missing, 426 then the "From:" line from the email header will be used to determine 427 the patch author in the changelog. 428 429 The explanation body will be committed to the permanent source 430 changelog, so should make sense to a competent reader who has long 431 since forgotten the immediate details of the discussion that might 432 have led to this patch. 433 434 The "---" marker line serves the essential purpose of marking for patch 435 handling tools where the changelog message ends. 436 437 One good use for the additional comments after the "---" marker is for 438 a diffstat, to show what files have changed, and the number of inserted 439 and deleted lines per file. A diffstat is especially useful on bigger 440 patches. Other comments relevant only to the moment or the maintainer, 441 not suitable for the permanent changelog, should also go here. 442 Use diffstat options "-p 1 -w 70" so that filenames are listed from the 443 top of the kernel source tree and don't use too much horizontal space 444 (easily fit in 80 columns, maybe with some indentation). 445 446 See more details on the proper patch format in the following 447 references. 448 449 450 451 452 ----------------------------------- 453 SECTION 2 - HINTS, TIPS, AND TRICKS 454 ----------------------------------- 455 456 This section lists many of the common "rules" associated with code 457 submitted to the kernel. There are always exceptions... but you must 458 have a really good reason for doing so. You could probably call this 459 section Linus Computer Science 101. 460 461 462 463 1) Read Documentation/CodingStyle 464 465 Nuff said. If your code deviates too much from this, it is likely 466 to be rejected without further review, and without comment. 467 468 One significant exception is when moving code from one file to 469 another -- in this case you should not modify the moved code at all in 470 the same patch which moves it. This clearly delineates the act of 471 moving the code and your changes. This greatly aids review of the 472 actual differences and allows tools to better track the history of 473 the code itself. 474 475 Check your patches with the patch style checker prior to submission 476 (scripts/checkpatch.pl). The style checker should be viewed as 477 a guide not as the final word. If your code looks better with 478 a violation then its probably best left alone. 479 480 The checker reports at three levels: 481 - ERROR: things that are very likely to be wrong 482 - WARNING: things requiring careful review 483 - CHECK: things requiring thought 484 485 You should be able to justify all violations that remain in your 486 patch. 487 488 489 490 2) #ifdefs are ugly 491 492 Code cluttered with ifdefs is difficult to read and maintain. Don't do 493 it. Instead, put your ifdefs in a header, and conditionally define 494 'static inline' functions, or macros, which are used in the code. 495 Let the compiler optimize away the "no-op" case. 496 497 Simple example, of poor code: 498 499 dev = alloc_etherdev (sizeof(struct funky_private)); 500 if (!dev) 501 return -ENODEV; 502 #ifdef CONFIG_NET_FUNKINESS 503 init_funky_net(dev); 504 #endif 505 506 Cleaned-up example: 507 508 (in header) 509 #ifndef CONFIG_NET_FUNKINESS 510 static inline void init_funky_net (struct net_device *d) {} 511 #endif 512 513 (in the code itself) 514 dev = alloc_etherdev (sizeof(struct funky_private)); 515 if (!dev) 516 return -ENODEV; 517 init_funky_net(dev); 518 519 520 521 3) 'static inline' is better than a macro 522 523 Static inline functions are greatly preferred over macros. 524 They provide type safety, have no length limitations, no formatting 525 limitations, and under gcc they are as cheap as macros. 526 527 Macros should only be used for cases where a static inline is clearly 528 suboptimal [there a few, isolated cases of this in fast paths], 529 or where it is impossible to use a static inline function [such as 530 string-izing]. 531 532 'static inline' is preferred over 'static __inline__', 'extern inline', 533 and 'extern __inline__'. 534 535 536 537 4) Don't over-design. 538 539 Don't try to anticipate nebulous future cases which may or may not 540 be useful: "Make it as simple as you can, and no simpler." 541 542 543 544 ---------------------- 545 SECTION 3 - REFERENCES 546 ---------------------- 547 548 Andrew Morton, "The perfect patch" (tpp). 549 <http://www.zip.com.au/~akpm/linux/patches/stuff/tpp.txt> 550 551 Jeff Garzik, "Linux kernel patch submission format". 552 <http://linux.yyz.us/patch-format.html> 553 554 Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". 555 <http://www.kroah.com/log/2005/03/31/> 556 <http://www.kroah.com/log/2005/07/08/> 557 <http://www.kroah.com/log/2005/10/19/> 558 <http://www.kroah.com/log/2006/01/11/> 559 560 NO!!!! No more huge patch bombs to linux-kernel (a] vger.kernel.org people! 561 <http://marc.theaimsgroup.com/?l=linux-kernel&m=112112749912944&w=2> 562 563 Kernel Documentation/CodingStyle: 564 <http://users.sosdg.org/~qiyong/lxr/source/Documentation/CodingStyle> 565 566 Linus Torvalds's mail on the canonical patch format: 567 <http://lkml.org/lkml/2005/4/7/183> 568 -- 569
