"Fossies" - the Fresh Open Source Software Archive

Member "syslinux-6.03/doc/SubmittingPatches.txt" (6 Oct 2014, 20815 Bytes) of package /linux/misc/syslinux-6.03.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    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@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@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@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@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@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@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@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 --