linux-3.3/Documentation/SubmittingPatches

31 generated by diff(1).  When creating your patch, make sure to create it
38 To create a patch for a single file, it is often sufficient to do:
47 	diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch
49 To create a patch for multiple files, you should unpack a "vanilla",
58 		linux-2.6.12-vanilla $MYSRC > /tmp/patch
62 patch.  The "dontdiff" file is included in the kernel tree in
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-
73 kernel developers, very important if you want your patch accepted.
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
88 Describe the technical detail of the change(s) your patch includes.
91 things like "update driver X", "bug fix for driver X", or "this patch
94 The maintainer will thank you if you write your patch description in a
99 need to split up your patch.  See #3, next.
101 When you submit or resubmit a patch or patch series, include the
102 complete patch description and justification for it.  Don't just
103 say that this is version N of the patch (series).  Don't expect the
104 patch merger to refer back to earlier patch versions or referenced
105 URLs to find the patch description and put that into the patch.
106 I.e., the patch (series) and its description should be self-contained.
107 This benefits both the patch merger(s) and reviewers.  Some reviewers
108 probably didn't even receive earlier versions of the patch.
110 If the patch fixes a logged bug entry, refer to that bug entry by
116 Separate _logical changes_ into a single patch file.
124 group those changes into a single patch.  Thus a single logical change
125 is contained within a single patch.
127 If one patch depends on another patch in order for a change to be
128 complete, that is OK.  Simply note "this patch depends on patch X"
129 in your patch description.
131 If you cannot condense your patch set into a smaller set of patches,
138 Check your patch for basic style violations, details of which can be
140 the reviewers time and will get your patch rejected, probably
143 At a minimum you should check your patches with the patch style
145 be able to justify all violations that remain in your patch.
156 your patch to the primary Linux kernel developer's mailing list,
172 usually be sent first to linux-kernel.  Only after the patch is
173 discussed should the patch then be submitted to Linus.
194 a man-pages patch, or at least a notification of the change,
213  Any fix by the author/maintainer of the file (ie. patch monkey
226 WARNING:  Be wary of your editor's word-wrap corrupting your patch,
227 if you choose to cut-n-paste your patch.
229 Do not attach the patch as a MIME attachment, compressed or not.
246 maintainers.  If your patch, uncompressed, exceeds 300 kB in size,
247 it is preferred that you store your patch on an Internet-accessible
248 server, and provide instead a URL (link) pointing to your patch.
254 It is important to note, either in the subject line or in the patch
255 description, the kernel version to which this patch applies.
257 If the patch does not apply cleanly to the latest kernel version,
273 It is quite common for Linus to "drop" your patch without comment.
274 That's the nature of the system.  If he drops your patch, it could be
276 * Your patch did not apply cleanly to the latest kernel version.
277 * Your patch was not sufficiently discussed on linux-kernel.
305 patch, which certifies that you wrote it or otherwise have the right to
306 pass it on as an open-source patch.  The rules are pretty simple: if you
369 to insert an indication of the origin of a patch at the top of the commit
395 development of the patch, or that he/she was in the patch's delivery path.
398 patch but wishes to signify and record their approval of it then they can
399 arrange to have an Acked-by: line added to the patch's changelog.
402 maintainer neither contributed to nor forwarded the patch.
405 has at least reviewed the patch and has indicated acceptance.  Hence patch
409 Acked-by: does not necessarily indicate acknowledgement of the entire patch.
410 For example, if a patch affects multiple subsystems and has an Acked-by: from
416 If a person has had the opportunity to comment on a patch, but has not
417 provided such comments, you may optionally add a "Cc:" tag to the patch.
425 If this patch fixes a problem reported by somebody else, consider adding a
432 A Tested-by: tag indicates that the patch has been successfully tested (in
437 Reviewed-by:, instead, indicates that the patch has been reviewed and found
444  	 (a) I have carried out a technical review of this patch to
448 	 (b) Any problems, concerns, or questions relating to the patch
457 	 (d) While I have reviewed the patch and believe it to be sound, I
462 A Reviewed-by tag is a statement of opinion that the patch is an
465 offer a Reviewed-by tag for a patch.  This tag serves to give credit to
467 done on the patch.  Reviewed-by: tags, when supplied by reviewers known to
469 increase the likelihood of your patch getting into the kernel.
472 15) The canonical patch format
474 The canonical patch subject line is:
478 The canonical patch message body contains the following:
480   - A "from" line specifying the patch author.
485     permanent changelog to describe this patch.
494   - The actual patch (diff output).
505 describe the patch which that email contains.  The "summary
507 phrase" for every patch in a whole patch series (where a "patch
511 globally-unique identifier for that patch.  It propagates all the way
513 developer discussions which refer to the patch.  People will want to
515 patch.  It will also be the only thing that people may quickly see
521 characters, and it must describe both what the patch changes, as well
522 as why the patch might be necessary.  It is challenging to be both
528 considered part of the summary phrase, but describe how the patch
530 the multiple versions of the patch have been sent out in response to
532 comments.  If there are four patches in a patch series the individual
536 the patch series.
540     Subject: [patch 2/5] ext2: improve scalability of bitmap searching
549 patch in the permanent changelog.  If the "from" line is missing,
551 the patch author in the changelog.
556 have led to this patch.  Including symptoms of the failure which the
557 patch addresses (kernel log messages, oops messages, etc.) is
559 looking for the applicable patch.  If a patch fixes a compile failure,
561 enough that it is likely that someone searching for the patch can find
565 The "---" marker line serves the essential purpose of marking for patch
573 here.  A good example of such comments might be "patch changelogs"
575 patch.
582 See more details on the proper patch format in the following
632 the same patch which moves it.  This clearly delineates the act of
637 Check your patches with the patch style checker prior to submission
648 patch.
710 Andrew Morton, "The perfect patch" (tpp).
713 Jeff Garzik, "Linux kernel patch submission format".
714   <http://linux.yyz.us/patch-format.html>
723 NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people!
729 Linus Torvalds's mail on the canonical patch format: