Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1759091Ab3EWMxQ (ORCPT ); Thu, 23 May 2013 08:53:16 -0400 Received: from mail-pa0-f51.google.com ([209.85.220.51]:63936 "EHLO mail-pa0-f51.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1759070Ab3EWMxJ (ORCPT ); Thu, 23 May 2013 08:53:09 -0400 From: Ben Minerds To: greg@kroah.com, rob@landley.net Cc: Ben Minerds , linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org Subject: [PATCH 8/8] Documentation: Move other patch related document Date: Thu, 23 May 2013 22:50:00 +1000 Message-Id: <2f43e77c031b137fac6d64fb602d6f84d9454a87.1369312746.git.PuZZleDucK@gmail.com> X-Mailer: git-send-email 1.8.1.2 In-Reply-To: References: In-Reply-To: References: Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 103604 Lines: 2442 Moved a couple of other patch related documents into the development-process/patches directory: applying-patches.txt and SubmittingPatches. Signed-off-by: Ben Minerds --- Documentation/SubmittingPatches | 743 --------------------- Documentation/applying-patches.txt | 454 ------------- .../development-process/patches/SubmittingPatches | 743 +++++++++++++++++++++ .../patches/applying-patches.txt | 454 +++++++++++++ 4 files changed, 1197 insertions(+), 1197 deletions(-) delete mode 100644 Documentation/SubmittingPatches delete mode 100644 Documentation/applying-patches.txt create mode 100644 Documentation/development-process/patches/SubmittingPatches create mode 100644 Documentation/development-process/patches/applying-patches.txt diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches deleted file mode 100644 index 8cd0e1e..0000000 --- a/Documentation/SubmittingPatches +++ /dev/null @@ -1,743 +0,0 @@ - - How to Get Your Change Into the Linux Kernel - or - Care And Operation Of Your Linus Torvalds - - - -For a person or company who wishes to submit a change to the Linux -kernel, the process can sometimes be daunting if you're not familiar -with "the system." This text is a collection of suggestions which -can greatly increase the chances of your change being accepted. - -Read Documentation/SubmitChecklist for a list of items to check -before submitting code. If you are submitting a driver, also read -Documentation/SubmittingDrivers. - - - --------------------------------------------- -SECTION 1 - CREATING AND SENDING YOUR CHANGE --------------------------------------------- - - - -1) "diff -up" ------------- - -Use "diff -up" or "diff -uprN" to create patches. - -All changes to the Linux kernel occur in the form of patches, as -generated by diff(1). When creating your patch, make sure to create it -in "unified diff" format, as supplied by the '-u' argument to diff(1). -Also, please use the '-p' argument which shows which C function each -change is in - that makes the resultant diff a lot easier to read. -Patches should be based in the root kernel source directory, -not in any lower subdirectory. - -To create a patch for a single file, it is often sufficient to do: - - SRCTREE= linux-2.6 - MYFILE= drivers/net/mydriver.c - - cd $SRCTREE - cp $MYFILE $MYFILE.orig - vi $MYFILE # make your change - cd .. - diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch - -To create a patch for multiple files, you should unpack a "vanilla", -or unmodified kernel source tree, and generate a diff against your -own source tree. For example: - - MYSRC= /devel/linux-2.6 - - tar xvfz linux-2.6.12.tar.gz - mv linux-2.6.12 linux-2.6.12-vanilla - diff -uprN -X linux-2.6.12-vanilla/Documentation/dontdiff \ - linux-2.6.12-vanilla $MYSRC > /tmp/patch - -"dontdiff" is a list of files which are generated by the kernel during -the build process, and should be ignored in any diff(1)-generated -patch. The "dontdiff" file is included in the kernel tree in -2.6.12 and later. - -Make sure your patch does not include any extra files which do not -belong in a patch submission. Make sure to review your patch -after- -generated it with diff(1), to ensure accuracy. - -If your changes produce a lot of deltas, you may want to look into -splitting them into individual patches which modify things in -logical stages. This will facilitate easier reviewing by other -kernel developers, very important if you want your patch accepted. -There are a number of scripts which can aid in this: - -Quilt: -http://savannah.nongnu.org/projects/quilt - -Andrew Morton's patch scripts: -http://userweb.kernel.org/~akpm/stuff/patch-scripts.tar.gz -Instead of these scripts, quilt is the recommended patch management -tool (see above). - - - -2) Describe your changes. - -Describe the technical detail of the change(s) your patch includes. - -Be as specific as possible. The WORST descriptions possible include -things like "update driver X", "bug fix for driver X", or "this patch -includes updates for subsystem X. Please apply." - -The maintainer will thank you if you write your patch description in a -form which can be easily pulled into Linux's source code management -system, git, as a "commit log". See #15, below. - -If your description starts to get long, that's a sign that you probably -need to split up your patch. See #3, next. - -When you submit or resubmit a patch or patch series, include the -complete patch description and justification for it. Don't just -say that this is version N of the patch (series). Don't expect the -patch merger to refer back to earlier patch versions or referenced -URLs to find the patch description and put that into the patch. -I.e., the patch (series) and its description should be self-contained. -This benefits both the patch merger(s) and reviewers. Some reviewers -probably didn't even receive earlier versions of the patch. - -If the patch fixes a logged bug entry, refer to that bug entry by -number and URL. - - -3) Separate your changes. - -Separate _logical changes_ into a single patch file. - -For example, if your changes include both bug fixes and performance -enhancements for a single driver, separate those changes into two -or more patches. If your changes include an API update, and a new -driver which uses that new API, separate those into two patches. - -On the other hand, if you make a single change to numerous files, -group those changes into a single patch. Thus a single logical change -is contained within a single patch. - -If one patch depends on another patch in order for a change to be -complete, that is OK. Simply note "this patch depends on patch X" -in your patch description. - -If you cannot condense your patch set into a smaller set of patches, -then only post say 15 or so at a time and wait for review and integration. - - - -4) Style check your changes. - -Check your patch for basic style violations, details of which can be -found in Documentation/CodingStyle. Failure to do so simply wastes -the reviewers time and will get your patch rejected, probably -without even being read. - -At a minimum you should check your patches with the patch style -checker prior to submission (scripts/checkpatch.pl). You should -be able to justify all violations that remain in your patch. - - - -5) Select e-mail destination. - -Look through the MAINTAINERS file and the source code, and determine -if your change applies to a specific subsystem of the kernel, with -an assigned maintainer. If so, e-mail that person. The script -scripts/get_maintainer.pl can be very useful at this step. - -If no maintainer is listed, or the maintainer does not respond, send -your patch to the primary Linux kernel developer's mailing list, -linux-kernel@vger.kernel.org. Most kernel developers monitor this -e-mail list, and can comment on your changes. - - -Do not send more than 15 patches at once to the vger mailing lists!!! - - -Linus Torvalds is the final arbiter of all changes accepted into the -Linux kernel. His e-mail address is . -He gets a lot of e-mail, so typically you should do your best to -avoid- -sending him e-mail. - -Patches which are bug fixes, are "obvious" changes, or similarly -require little discussion should be sent or CC'd to Linus. Patches -which require discussion or do not have a clear advantage should -usually be sent first to linux-kernel. Only after the patch is -discussed should the patch then be submitted to Linus. - - - -6) Select your CC (e-mail carbon copy) list. - -Unless you have a reason NOT to do so, CC linux-kernel@vger.kernel.org. - -Other kernel developers besides Linus need to be aware of your change, -so that they may comment on it and offer code review and suggestions. -linux-kernel is the primary Linux kernel developer mailing list. -Other mailing lists are available for specific subsystems, such as -USB, framebuffer devices, the VFS, the SCSI subsystem, etc. See the -MAINTAINERS file for a mailing list that relates specifically to -your change. - -Majordomo lists of VGER.KERNEL.ORG at: - - -If changes affect userland-kernel interfaces, please send -the MAN-PAGES maintainer (as listed in the MAINTAINERS file) -a man-pages patch, or at least a notification of the change, -so that some information makes its way into the manual pages. - -Even if the maintainer did not respond in step #5, make sure to ALWAYS -copy the maintainer when you change their code. - -For small patches you may want to CC the Trivial Patch Monkey -trivial@kernel.org which collects "trivial" patches. Have a look -into the MAINTAINERS file for its current manager. -Trivial patches must qualify for one of the following rules: - Spelling fixes in documentation - Spelling fixes which could break grep(1) - Warning fixes (cluttering with useless warnings is bad) - Compilation fixes (only if they are actually correct) - Runtime fixes (only if they actually fix things) - Removing use of deprecated functions/macros (eg. check_region) - Contact detail and documentation fixes - Non-portable code replaced by portable code (even in arch-specific, - since people copy, as long as it's trivial) - Any fix by the author/maintainer of the file (ie. patch monkey - in re-transmission mode) - - - -7) No MIME, no links, no compression, no attachments. Just plain text. - -Linus and other kernel developers need to be able to read and comment -on the changes you are submitting. It is important for a kernel -developer to be able to "quote" your changes, using standard e-mail -tools, so that they may comment on specific portions of your code. - -For this reason, all patches should be submitting e-mail "inline". -WARNING: Be wary of your editor's word-wrap corrupting your patch, -if you choose to cut-n-paste your patch. - -Do not attach the patch as a MIME attachment, compressed or not. -Many popular e-mail applications will not always transmit a MIME -attachment as plain text, making it impossible to comment on your -code. A MIME attachment also takes Linus a bit more time to process, -decreasing the likelihood of your MIME-attached change being accepted. - -Exception: If your mailer is mangling patches then someone may ask -you to re-send them using MIME. - -See Documentation/email-clients.txt for hints about configuring -your e-mail client so that it sends your patches untouched. - -8) E-mail size. - -When sending patches to Linus, always follow step #7. - -Large changes are not appropriate for mailing lists, and some -maintainers. If your patch, uncompressed, exceeds 300 kB in size, -it is preferred that you store your patch on an Internet-accessible -server, and provide instead a URL (link) pointing to your patch. - - - -9) Name your kernel version. - -It is important to note, either in the subject line or in the patch -description, the kernel version to which this patch applies. - -If the patch does not apply cleanly to the latest kernel version, -Linus will not apply it. - - - -10) Don't get discouraged. Re-submit. - -After you have submitted your change, be patient and wait. If Linus -likes your change and applies it, it will appear in the next version -of the kernel that he releases. - -However, if your change doesn't appear in the next version of the -kernel, there could be any number of reasons. It's YOUR job to -narrow down those reasons, correct what was wrong, and submit your -updated change. - -It is quite common for Linus to "drop" your patch without comment. -That's the nature of the system. If he drops your patch, it could be -due to -* Your patch did not apply cleanly to the latest kernel version. -* Your patch was not sufficiently discussed on linux-kernel. -* A style issue (see section 2). -* An e-mail formatting issue (re-read this section). -* A technical problem with your change. -* He gets tons of e-mail, and yours got lost in the shuffle. -* You are being annoying. - -When in doubt, solicit comments on linux-kernel mailing list. - - - -11) Include PATCH in the subject - -Due to high e-mail traffic to Linus, and to linux-kernel, it is common -convention to prefix your subject line with [PATCH]. This lets Linus -and other kernel developers more easily distinguish patches from other -e-mail discussions. - - - -12) Sign your work - -To improve tracking of who did what, especially with patches that can -percolate to their final resting place in the kernel through several -layers of maintainers, we've introduced a "sign-off" procedure on -patches that are being emailed around. - -The sign-off is a simple line at the end of the explanation for the -patch, which certifies that you wrote it or otherwise have the right to -pass it on as an open-source patch. The rules are pretty simple: if you -can certify the below: - - Developer's Certificate of Origin 1.1 - - By making a contribution to this project, I certify that: - - (a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or - - (b) The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or - - (c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. - - (d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. - -then you just add a line saying - - Signed-off-by: Random J Developer - -using your real name (sorry, no pseudonyms or anonymous contributions.) - -Some people also put extra tags at the end. They'll just be ignored for -now, but you can do this to mark internal company procedures or just -point out some special detail about the sign-off. - -If you are a subsystem or branch maintainer, sometimes you need to slightly -modify patches you receive in order to merge them, because the code is not -exactly the same in your tree and the submitters'. If you stick strictly to -rule (c), you should ask the submitter to rediff, but this is a totally -counter-productive waste of time and energy. Rule (b) allows you to adjust -the code, but then it is very impolite to change one submitter's code and -make him endorse your bugs. To solve this problem, it is recommended that -you add a line between the last Signed-off-by header and yours, indicating -the nature of your changes. While there is nothing mandatory about this, it -seems like prepending the description with your mail and/or name, all -enclosed in square brackets, is noticeable enough to make it obvious that -you are responsible for last-minute changes. Example : - - Signed-off-by: Random J Developer - [lucky@maintainer.example.org: struct foo moved from foo.c to foo.h] - Signed-off-by: Lucky K Maintainer - -This practise is particularly helpful if you maintain a stable branch and -want at the same time to credit the author, track changes, merge the fix, -and protect the submitter from complaints. Note that under no circumstances -can you change the author's identity (the From header), as it is the one -which appears in the changelog. - -Special note to back-porters: It seems to be a common and useful practise -to insert an indication of the origin of a patch at the top of the commit -message (just after the subject line) to facilitate tracking. For instance, -here's what we see in 2.6-stable : - - Date: Tue May 13 19:10:30 2008 +0000 - - SCSI: libiscsi regression in 2.6.25: fix nop timer handling - - commit 4cf1043593db6a337f10e006c23c69e5fc93e722 upstream - -And here's what appears in 2.4 : - - Date: Tue May 13 22:12:27 2008 +0200 - - wireless, airo: waitbusy() won't delay - - [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a] - -Whatever the format, this information provides a valuable help to people -tracking your trees, and to people trying to trouble-shoot bugs in your -tree. - - -13) When to use Acked-by: and Cc: - -The Signed-off-by: tag indicates that the signer was involved in the -development of the patch, or that he/she was in the patch's delivery path. - -If a person was not directly involved in the preparation or handling of a -patch but wishes to signify and record their approval of it then they can -arrange to have an Acked-by: line added to the patch's changelog. - -Acked-by: is often used by the maintainer of the affected code when that -maintainer neither contributed to nor forwarded the patch. - -Acked-by: is not as formal as Signed-off-by:. It is a record that the acker -has at least reviewed the patch and has indicated acceptance. Hence patch -mergers will sometimes manually convert an acker's "yep, looks good to me" -into an Acked-by:. - -Acked-by: does not necessarily indicate acknowledgement of the entire patch. -For example, if a patch affects multiple subsystems and has an Acked-by: from -one subsystem maintainer then this usually indicates acknowledgement of just -the part which affects that maintainer's code. Judgement should be used here. -When in doubt people should refer to the original discussion in the mailing -list archives. - -If a person has had the opportunity to comment on a patch, but has not -provided such comments, you may optionally add a "Cc:" tag to the patch. -This is the only tag which might be added without an explicit action by the -person it names. This tag documents that potentially interested parties -have been included in the discussion - - -14) Using Reported-by:, Tested-by:, Reviewed-by: and Suggested-by: - -If this patch fixes a problem reported by somebody else, consider adding a -Reported-by: tag to credit the reporter for their contribution. Please -note that this tag should not be added without the reporter's permission, -especially if the problem was not reported in a public forum. That said, -if we diligently credit our bug reporters, they will, hopefully, be -inspired to help us again in the future. - -A Tested-by: tag indicates that the patch has been successfully tested (in -some environment) by the person named. This tag informs maintainers that -some testing has been performed, provides a means to locate testers for -future patches, and ensures credit for the testers. - -Reviewed-by:, instead, indicates that the patch has been reviewed and found -acceptable according to the Reviewer's Statement: - - Reviewer's statement of oversight - - By offering my Reviewed-by: tag, I state that: - - (a) I have carried out a technical review of this patch to - evaluate its appropriateness and readiness for inclusion into - the mainline kernel. - - (b) Any problems, concerns, or questions relating to the patch - have been communicated back to the submitter. I am satisfied - with the submitter's response to my comments. - - (c) While there may be things that could be improved with this - submission, I believe that it is, at this time, (1) a - worthwhile modification to the kernel, and (2) free of known - issues which would argue against its inclusion. - - (d) While I have reviewed the patch and believe it to be sound, I - do not (unless explicitly stated elsewhere) make any - warranties or guarantees that it will achieve its stated - purpose or function properly in any given situation. - -A Reviewed-by tag is a statement of opinion that the patch is an -appropriate modification of the kernel without any remaining serious -technical issues. Any interested reviewer (who has done the work) can -offer a Reviewed-by tag for a patch. This tag serves to give credit to -reviewers and to inform maintainers of the degree of review which has been -done on the patch. Reviewed-by: tags, when supplied by reviewers known to -understand the subject area and to perform thorough reviews, will normally -increase the likelihood of your patch getting into the kernel. - -A Suggested-by: tag indicates that the patch idea is suggested by the person -named and ensures credit to the person for the idea. Please note that this -tag should not be added without the reporter's permission, especially if the -idea was not posted in a public forum. That said, if we diligently credit our -idea reporters, they will, hopefully, be inspired to help us again in the -future. - - -15) The canonical patch format - -The canonical patch subject line is: - - Subject: [PATCH 001/123] subsystem: summary phrase - -The canonical patch message body contains the following: - - - A "from" line specifying the patch author. - - - An empty line. - - - The body of the explanation, which will be copied to the - permanent changelog to describe this patch. - - - The "Signed-off-by:" lines, described above, which will - also go in the changelog. - - - A marker line containing simply "---". - - - Any additional comments not suitable for the changelog. - - - The actual patch (diff output). - -The Subject line format makes it very easy to sort the emails -alphabetically by subject line - pretty much any email reader will -support that - since because the sequence number is zero-padded, -the numerical and alphabetic sort is the same. - -The "subsystem" in the email's Subject should identify which -area or subsystem of the kernel is being patched. - -The "summary phrase" in the email's Subject should concisely -describe the patch which that email contains. The "summary -phrase" should not be a filename. Do not use the same "summary -phrase" for every patch in a whole patch series (where a "patch -series" is an ordered sequence of multiple, related patches). - -Bear in mind that the "summary phrase" of your email becomes a -globally-unique identifier for that patch. It propagates all the way -into the git changelog. The "summary phrase" may later be used in -developer discussions which refer to the patch. People will want to -google for the "summary phrase" to read discussion regarding that -patch. It will also be the only thing that people may quickly see -when, two or three months later, they are going through perhaps -thousands of patches using tools such as "gitk" or "git log ---oneline". - -For these reasons, the "summary" must be no more than 70-75 -characters, and it must describe both what the patch changes, as well -as why the patch might be necessary. It is challenging to be both -succinct and descriptive, but that is what a well-written summary -should do. - -The "summary phrase" may be prefixed by tags enclosed in square -brackets: "Subject: [PATCH tag] ". The tags are not -considered part of the summary phrase, but describe how the patch -should be treated. Common tags might include a version descriptor if -the multiple versions of the patch have been sent out in response to -comments (i.e., "v1, v2, v3"), or "RFC" to indicate a request for -comments. If there are four patches in a patch series the individual -patches may be numbered like this: 1/4, 2/4, 3/4, 4/4. This assures -that developers understand the order in which the patches should be -applied and that they have reviewed or applied all of the patches in -the patch series. - -A couple of example Subjects: - - Subject: [patch 2/5] ext2: improve scalability of bitmap searching - Subject: [PATCHv2 001/207] x86: fix eflags tracking - -The "from" line must be the very first line in the message body, -and has the form: - - From: Original Author - -The "from" line specifies who will be credited as the author of the -patch in the permanent changelog. If the "from" line is missing, -then the "From:" line from the email header will be used to determine -the patch author in the changelog. - -The explanation body will be committed to the permanent source -changelog, so should make sense to a competent reader who has long -since forgotten the immediate details of the discussion that might -have led to this patch. Including symptoms of the failure which the -patch addresses (kernel log messages, oops messages, etc.) is -especially useful for people who might be searching the commit logs -looking for the applicable patch. If a patch fixes a compile failure, -it may not be necessary to include _all_ of the compile failures; just -enough that it is likely that someone searching for the patch can find -it. As in the "summary phrase", it is important to be both succinct as -well as descriptive. - -The "---" marker line serves the essential purpose of marking for patch -handling tools where the changelog message ends. - -One good use for the additional comments after the "---" marker is for -a diffstat, to show what files have changed, and the number of -inserted and deleted lines per file. A diffstat is especially useful -on bigger patches. Other comments relevant only to the moment or the -maintainer, not suitable for the permanent changelog, should also go -here. A good example of such comments might be "patch changelogs" -which describe what has changed between the v1 and v2 version of the -patch. - -If you are going to include a diffstat after the "---" marker, please -use diffstat options "-p 1 -w 70" so that filenames are listed from -the top of the kernel source tree and don't use too much horizontal -space (easily fit in 80 columns, maybe with some indentation). - -See more details on the proper patch format in the following -references. - - -16) Sending "git pull" requests (from Linus emails) - -Please write the git repo address and branch name alone on the same line -so that I can't even by mistake pull from the wrong branch, and so -that a triple-click just selects the whole thing. - -So the proper format is something along the lines of: - - "Please pull from - - git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus - - to get these changes:" - -so that I don't have to hunt-and-peck for the address and inevitably -get it wrong (actually, I've only gotten it wrong a few times, and -checking against the diffstat tells me when I get it wrong, but I'm -just a lot more comfortable when I don't have to "look for" the right -thing to pull, and double-check that I have the right branch-name). - - -Please use "git diff -M --stat --summary" to generate the diffstat: -the -M enables rename detection, and the summary enables a summary of -new/deleted or renamed files. - -With rename detection, the statistics are rather different [...] -because git will notice that a fair number of the changes are renames. - ------------------------------------ -SECTION 2 - HINTS, TIPS, AND TRICKS ------------------------------------ - -This section lists many of the common "rules" associated with code -submitted to the kernel. There are always exceptions... but you must -have a really good reason for doing so. You could probably call this -section Linus Computer Science 101. - - - -1) Read Documentation/CodingStyle - -Nuff said. If your code deviates too much from this, it is likely -to be rejected without further review, and without comment. - -One significant exception is when moving code from one file to -another -- in this case you should not modify the moved code at all in -the same patch which moves it. This clearly delineates the act of -moving the code and your changes. This greatly aids review of the -actual differences and allows tools to better track the history of -the code itself. - -Check your patches with the patch style checker prior to submission -(scripts/checkpatch.pl). The style checker should be viewed as -a guide not as the final word. If your code looks better with -a violation then its probably best left alone. - -The checker reports at three levels: - - ERROR: things that are very likely to be wrong - - WARNING: things requiring careful review - - CHECK: things requiring thought - -You should be able to justify all violations that remain in your -patch. - - - -2) #ifdefs are ugly - -Code cluttered with ifdefs is difficult to read and maintain. Don't do -it. Instead, put your ifdefs in a header, and conditionally define -'static inline' functions, or macros, which are used in the code. -Let the compiler optimize away the "no-op" case. - -Simple example, of poor code: - - dev = alloc_etherdev (sizeof(struct funky_private)); - if (!dev) - return -ENODEV; - #ifdef CONFIG_NET_FUNKINESS - init_funky_net(dev); - #endif - -Cleaned-up example: - -(in header) - #ifndef CONFIG_NET_FUNKINESS - static inline void init_funky_net (struct net_device *d) {} - #endif - -(in the code itself) - dev = alloc_etherdev (sizeof(struct funky_private)); - if (!dev) - return -ENODEV; - init_funky_net(dev); - - - -3) 'static inline' is better than a macro - -Static inline functions are greatly preferred over macros. -They provide type safety, have no length limitations, no formatting -limitations, and under gcc they are as cheap as macros. - -Macros should only be used for cases where a static inline is clearly -suboptimal [there are a few, isolated cases of this in fast paths], -or where it is impossible to use a static inline function [such as -string-izing]. - -'static inline' is preferred over 'static __inline__', 'extern inline', -and 'extern __inline__'. - - - -4) Don't over-design. - -Don't try to anticipate nebulous future cases which may or may not -be useful: "Make it as simple as you can, and no simpler." - - - ----------------------- -SECTION 3 - REFERENCES ----------------------- - -Andrew Morton, "The perfect patch" (tpp). - Documentation/development-process/patches/The-Perfect-Patch.txt - -Jeff Garzik, "Linux kernel patch submission format". - Documentation/development-process/patches/Patch-Submission-Format.txt - -Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". - - - - - - -NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! - - -Kernel Documentation/CodingStyle: - - -Linus Torvalds's mail on the canonical patch format: - - -Andi Kleen, "On submitting kernel patches" - Some strategies to get difficult or controversial changes in. - http://halobates.de/on-submitting-patches.pdf - --- diff --git a/Documentation/applying-patches.txt b/Documentation/applying-patches.txt deleted file mode 100644 index a083ba3..0000000 --- a/Documentation/applying-patches.txt +++ /dev/null @@ -1,454 +0,0 @@ - - Applying Patches To The Linux Kernel - ------------------------------------ - - Original by: Jesper Juhl, August 2005 - Last update: 2006-01-05 - - -A frequently asked question on the Linux Kernel Mailing List is how to apply -a patch to the kernel or, more specifically, what base kernel a patch for -one of the many trees/branches should be applied to. Hopefully this document -will explain this to you. - -In addition to explaining how to apply and revert patches, a brief -description of the different kernel trees (and examples of how to apply -their specific patches) is also provided. - - -What is a patch? ---- - A patch is a small text document containing a delta of changes between two -different versions of a source tree. Patches are created with the `diff' -program. -To correctly apply a patch you need to know what base it was generated from -and what new version the patch will change the source tree into. These -should both be present in the patch file metadata or be possible to deduce -from the filename. - - -How do I apply or revert a patch? ---- - You apply a patch with the `patch' program. The patch program reads a diff -(or patch) file and makes the changes to the source tree described in it. - -Patches for the Linux kernel are generated relative to the parent directory -holding the kernel source dir. - -This means that paths to files inside the patch file contain the name of the -kernel source directories it was generated against (or some other directory -names like "a/" and "b/"). -Since this is unlikely to match the name of the kernel source dir on your -local machine (but is often useful info to see what version an otherwise -unlabeled patch was generated against) you should change into your kernel -source directory and then strip the first element of the path from filenames -in the patch file when applying it (the -p1 argument to `patch' does this). - -To revert a previously applied patch, use the -R argument to patch. -So, if you applied a patch like this: - patch -p1 < ../patch-x.y.z - -You can revert (undo) it like this: - patch -R -p1 < ../patch-x.y.z - - -How do I feed a patch/diff file to `patch'? ---- - This (as usual with Linux and other UNIX like operating systems) can be -done in several different ways. -In all the examples below I feed the file (in uncompressed form) to patch -via stdin using the following syntax: - patch -p1 < path/to/patch-x.y.z - -If you just want to be able to follow the examples below and don't want to -know of more than one way to use patch, then you can stop reading this -section here. - -Patch can also get the name of the file to use via the -i argument, like -this: - patch -p1 -i path/to/patch-x.y.z - -If your patch file is compressed with gzip or bzip2 and you don't want to -uncompress it before applying it, then you can feed it to patch like this -instead: - zcat path/to/patch-x.y.z.gz | patch -p1 - bzcat path/to/patch-x.y.z.bz2 | patch -p1 - -If you wish to uncompress the patch file by hand first before applying it -(what I assume you've done in the examples below), then you simply run -gunzip or bunzip2 on the file -- like this: - gunzip patch-x.y.z.gz - bunzip2 patch-x.y.z.bz2 - -Which will leave you with a plain text patch-x.y.z file that you can feed to -patch via stdin or the -i argument, as you prefer. - -A few other nice arguments for patch are -s which causes patch to be silent -except for errors which is nice to prevent errors from scrolling out of the -screen too fast, and --dry-run which causes patch to just print a listing of -what would happen, but doesn't actually make any changes. Finally --verbose -tells patch to print more information about the work being done. - - -Common errors when patching ---- - When patch applies a patch file it attempts to verify the sanity of the -file in different ways. -Checking that the file looks like a valid patch file & checking the code -around the bits being modified matches the context provided in the patch are -just two of the basic sanity checks patch does. - -If patch encounters something that doesn't look quite right it has two -options. It can either refuse to apply the changes and abort or it can try -to find a way to make the patch apply with a few minor changes. - -One example of something that's not 'quite right' that patch will attempt to -fix up is if all the context matches, the lines being changed match, but the -line numbers are different. This can happen, for example, if the patch makes -a change in the middle of the file but for some reasons a few lines have -been added or removed near the beginning of the file. In that case -everything looks good it has just moved up or down a bit, and patch will -usually adjust the line numbers and apply the patch. - -Whenever patch applies a patch that it had to modify a bit to make it fit -it'll tell you about it by saying the patch applied with 'fuzz'. -You should be wary of such changes since even though patch probably got it -right it doesn't /always/ get it right, and the result will sometimes be -wrong. - -When patch encounters a change that it can't fix up with fuzz it rejects it -outright and leaves a file with a .rej extension (a reject file). You can -read this file to see exactly what change couldn't be applied, so you can -go fix it up by hand if you wish. - -If you don't have any third-party patches applied to your kernel source, but -only patches from kernel.org and you apply the patches in the correct order, -and have made no modifications yourself to the source files, then you should -never see a fuzz or reject message from patch. If you do see such messages -anyway, then there's a high risk that either your local source tree or the -patch file is corrupted in some way. In that case you should probably try -re-downloading the patch and if things are still not OK then you'd be advised -to start with a fresh tree downloaded in full from kernel.org. - -Let's look a bit more at some of the messages patch can produce. - -If patch stops and presents a "File to patch:" prompt, then patch could not -find a file to be patched. Most likely you forgot to specify -p1 or you are -in the wrong directory. Less often, you'll find patches that need to be -applied with -p0 instead of -p1 (reading the patch file should reveal if -this is the case -- if so, then this is an error by the person who created -the patch but is not fatal). - -If you get "Hunk #2 succeeded at 1887 with fuzz 2 (offset 7 lines)." or a -message similar to that, then it means that patch had to adjust the location -of the change (in this example it needed to move 7 lines from where it -expected to make the change to make it fit). -The resulting file may or may not be OK, depending on the reason the file -was different than expected. -This often happens if you try to apply a patch that was generated against a -different kernel version than the one you are trying to patch. - -If you get a message like "Hunk #3 FAILED at 2387.", then it means that the -patch could not be applied correctly and the patch program was unable to -fuzz its way through. This will generate a .rej file with the change that -caused the patch to fail and also a .orig file showing you the original -content that couldn't be changed. - -If you get "Reversed (or previously applied) patch detected! Assume -R? [n]" -then patch detected that the change contained in the patch seems to have -already been made. -If you actually did apply this patch previously and you just re-applied it -in error, then just say [n]o and abort this patch. If you applied this patch -previously and actually intended to revert it, but forgot to specify -R, -then you can say [y]es here to make patch revert it for you. -This can also happen if the creator of the patch reversed the source and -destination directories when creating the patch, and in that case reverting -the patch will in fact apply it. - -A message similar to "patch: **** unexpected end of file in patch" or "patch -unexpectedly ends in middle of line" means that patch could make no sense of -the file you fed to it. Either your download is broken, you tried to feed -patch a compressed patch file without uncompressing it first, or the patch -file that you are using has been mangled by a mail client or mail transfer -agent along the way somewhere, e.g., by splitting a long line into two lines. -Often these warnings can easily be fixed by joining (concatenating) the -two lines that had been split. - -As I already mentioned above, these errors should never happen if you apply -a patch from kernel.org to the correct version of an unmodified source tree. -So if you get these errors with kernel.org patches then you should probably -assume that either your patch file or your tree is broken and I'd advise you -to start over with a fresh download of a full kernel tree and the patch you -wish to apply. - - -Are there any alternatives to `patch'? ---- - Yes there are alternatives. - - You can use the `interdiff' program (http://cyberelk.net/tim/patchutils/) to -generate a patch representing the differences between two patches and then -apply the result. -This will let you move from something like 2.6.12.2 to 2.6.12.3 in a single -step. The -z flag to interdiff will even let you feed it patches in gzip or -bzip2 compressed form directly without the use of zcat or bzcat or manual -decompression. - -Here's how you'd go from 2.6.12.2 to 2.6.12.3 in a single step: - interdiff -z ../patch-2.6.12.2.bz2 ../patch-2.6.12.3.gz | patch -p1 - -Although interdiff may save you a step or two you are generally advised to -do the additional steps since interdiff can get things wrong in some cases. - - Another alternative is `ketchup', which is a python script for automatic -downloading and applying of patches (http://www.selenic.com/ketchup/). - - Other nice tools are diffstat, which shows a summary of changes made by a -patch; lsdiff, which displays a short listing of affected files in a patch -file, along with (optionally) the line numbers of the start of each patch; -and grepdiff, which displays a list of the files modified by a patch where -the patch contains a given regular expression. - - -Where can I download the patches? ---- - The patches are available at http://kernel.org/ -Most recent patches are linked from the front page, but they also have -specific homes. - -The 2.6.x.y (-stable) and 2.6.x patches live at - ftp://ftp.kernel.org/pub/linux/kernel/v2.6/ - -The -rc patches live at - ftp://ftp.kernel.org/pub/linux/kernel/v2.6/testing/ - -The -git patches live at - ftp://ftp.kernel.org/pub/linux/kernel/v2.6/snapshots/ - -The -mm kernels live at - ftp://ftp.kernel.org/pub/linux/kernel/people/akpm/patches/2.6/ - -In place of ftp.kernel.org you can use ftp.cc.kernel.org, where cc is a -country code. This way you'll be downloading from a mirror site that's most -likely geographically closer to you, resulting in faster downloads for you, -less bandwidth used globally and less load on the main kernel.org servers -- -these are good things, so do use mirrors when possible. - - -The 2.6.x kernels ---- - These are the base stable releases released by Linus. The highest numbered -release is the most recent. - -If regressions or other serious flaws are found, then a -stable fix patch -will be released (see below) on top of this base. Once a new 2.6.x base -kernel is released, a patch is made available that is a delta between the -previous 2.6.x kernel and the new one. - -To apply a patch moving from 2.6.11 to 2.6.12, you'd do the following (note -that such patches do *NOT* apply on top of 2.6.x.y kernels but on top of the -base 2.6.x kernel -- if you need to move from 2.6.x.y to 2.6.x+1 you need to -first revert the 2.6.x.y patch). - -Here are some examples: - -# moving from 2.6.11 to 2.6.12 -$ cd ~/linux-2.6.11 # change to kernel source dir -$ patch -p1 < ../patch-2.6.12 # apply the 2.6.12 patch -$ cd .. -$ mv linux-2.6.11 linux-2.6.12 # rename source dir - -# moving from 2.6.11.1 to 2.6.12 -$ cd ~/linux-2.6.11.1 # change to kernel source dir -$ patch -p1 -R < ../patch-2.6.11.1 # revert the 2.6.11.1 patch - # source dir is now 2.6.11 -$ patch -p1 < ../patch-2.6.12 # apply new 2.6.12 patch -$ cd .. -$ mv linux-2.6.11.1 linux-2.6.12 # rename source dir - - -The 2.6.x.y kernels ---- - Kernels with 4-digit versions are -stable kernels. They contain small(ish) -critical fixes for security problems or significant regressions discovered -in a given 2.6.x kernel. - -This is the recommended branch for users who want the most recent stable -kernel and are not interested in helping test development/experimental -versions. - -If no 2.6.x.y kernel is available, then the highest numbered 2.6.x kernel is -the current stable kernel. - - note: the -stable team usually do make incremental patches available as well - as patches against the latest mainline release, but I only cover the - non-incremental ones below. The incremental ones can be found at - ftp://ftp.kernel.org/pub/linux/kernel/v2.6/incr/ - -These patches are not incremental, meaning that for example the 2.6.12.3 -patch does not apply on top of the 2.6.12.2 kernel source, but rather on top -of the base 2.6.12 kernel source . -So, in order to apply the 2.6.12.3 patch to your existing 2.6.12.2 kernel -source you have to first back out the 2.6.12.2 patch (so you are left with a -base 2.6.12 kernel source) and then apply the new 2.6.12.3 patch. - -Here's a small example: - -$ cd ~/linux-2.6.12.2 # change into the kernel source dir -$ patch -p1 -R < ../patch-2.6.12.2 # revert the 2.6.12.2 patch -$ patch -p1 < ../patch-2.6.12.3 # apply the new 2.6.12.3 patch -$ cd .. -$ mv linux-2.6.12.2 linux-2.6.12.3 # rename the kernel source dir - - -The -rc kernels ---- - These are release-candidate kernels. These are development kernels released -by Linus whenever he deems the current git (the kernel's source management -tool) tree to be in a reasonably sane state adequate for testing. - -These kernels are not stable and you should expect occasional breakage if -you intend to run them. This is however the most stable of the main -development branches and is also what will eventually turn into the next -stable kernel, so it is important that it be tested by as many people as -possible. - -This is a good branch to run for people who want to help out testing -development kernels but do not want to run some of the really experimental -stuff (such people should see the sections about -git and -mm kernels below). - -The -rc patches are not incremental, they apply to a base 2.6.x kernel, just -like the 2.6.x.y patches described above. The kernel version before the -rcN -suffix denotes the version of the kernel that this -rc kernel will eventually -turn into. -So, 2.6.13-rc5 means that this is the fifth release candidate for the 2.6.13 -kernel and the patch should be applied on top of the 2.6.12 kernel source. - -Here are 3 examples of how to apply these patches: - -# first an example of moving from 2.6.12 to 2.6.13-rc3 -$ cd ~/linux-2.6.12 # change into the 2.6.12 source dir -$ patch -p1 < ../patch-2.6.13-rc3 # apply the 2.6.13-rc3 patch -$ cd .. -$ mv linux-2.6.12 linux-2.6.13-rc3 # rename the source dir - -# now let's move from 2.6.13-rc3 to 2.6.13-rc5 -$ cd ~/linux-2.6.13-rc3 # change into the 2.6.13-rc3 dir -$ patch -p1 -R < ../patch-2.6.13-rc3 # revert the 2.6.13-rc3 patch -$ patch -p1 < ../patch-2.6.13-rc5 # apply the new 2.6.13-rc5 patch -$ cd .. -$ mv linux-2.6.13-rc3 linux-2.6.13-rc5 # rename the source dir - -# finally let's try and move from 2.6.12.3 to 2.6.13-rc5 -$ cd ~/linux-2.6.12.3 # change to the kernel source dir -$ patch -p1 -R < ../patch-2.6.12.3 # revert the 2.6.12.3 patch -$ patch -p1 < ../patch-2.6.13-rc5 # apply new 2.6.13-rc5 patch -$ cd .. -$ mv linux-2.6.12.3 linux-2.6.13-rc5 # rename the kernel source dir - - -The -git kernels ---- - These are daily snapshots of Linus' kernel tree (managed in a git -repository, hence the name). - -These patches are usually released daily and represent the current state of -Linus's tree. They are more experimental than -rc kernels since they are -generated automatically without even a cursory glance to see if they are -sane. - --git patches are not incremental and apply either to a base 2.6.x kernel or -a base 2.6.x-rc kernel -- you can see which from their name. -A patch named 2.6.12-git1 applies to the 2.6.12 kernel source and a patch -named 2.6.13-rc3-git2 applies to the source of the 2.6.13-rc3 kernel. - -Here are some examples of how to apply these patches: - -# moving from 2.6.12 to 2.6.12-git1 -$ cd ~/linux-2.6.12 # change to the kernel source dir -$ patch -p1 < ../patch-2.6.12-git1 # apply the 2.6.12-git1 patch -$ cd .. -$ mv linux-2.6.12 linux-2.6.12-git1 # rename the kernel source dir - -# moving from 2.6.12-git1 to 2.6.13-rc2-git3 -$ cd ~/linux-2.6.12-git1 # change to the kernel source dir -$ patch -p1 -R < ../patch-2.6.12-git1 # revert the 2.6.12-git1 patch - # we now have a 2.6.12 kernel -$ patch -p1 < ../patch-2.6.13-rc2 # apply the 2.6.13-rc2 patch - # the kernel is now 2.6.13-rc2 -$ patch -p1 < ../patch-2.6.13-rc2-git3 # apply the 2.6.13-rc2-git3 patch - # the kernel is now 2.6.13-rc2-git3 -$ cd .. -$ mv linux-2.6.12-git1 linux-2.6.13-rc2-git3 # rename source dir - - -The -mm kernels ---- - These are experimental kernels released by Andrew Morton. - -The -mm tree serves as a sort of proving ground for new features and other -experimental patches. -Once a patch has proved its worth in -mm for a while Andrew pushes it on to -Linus for inclusion in mainline. - -Although it's encouraged that patches flow to Linus via the -mm tree, this -is not always enforced. -Subsystem maintainers (or individuals) sometimes push their patches directly -to Linus, even though (or after) they have been merged and tested in -mm (or -sometimes even without prior testing in -mm). - -You should generally strive to get your patches into mainline via -mm to -ensure maximum testing. - -This branch is in constant flux and contains many experimental features, a -lot of debugging patches not appropriate for mainline etc., and is the most -experimental of the branches described in this document. - -These kernels are not appropriate for use on systems that are supposed to be -stable and they are more risky to run than any of the other branches (make -sure you have up-to-date backups -- that goes for any experimental kernel but -even more so for -mm kernels). - -These kernels in addition to all the other experimental patches they contain -usually also contain any changes in the mainline -git kernels available at -the time of release. - -Testing of -mm kernels is greatly appreciated since the whole point of the -tree is to weed out regressions, crashes, data corruption bugs, build -breakage (and any other bug in general) before changes are merged into the -more stable mainline Linus tree. -But testers of -mm should be aware that breakage in this tree is more common -than in any other tree. - -The -mm kernels are not released on a fixed schedule, but usually a few -mm -kernels are released in between each -rc kernel (1 to 3 is common). -The -mm kernels apply to either a base 2.6.x kernel (when no -rc kernels -have been released yet) or to a Linus -rc kernel. - -Here are some examples of applying the -mm patches: - -# moving from 2.6.12 to 2.6.12-mm1 -$ cd ~/linux-2.6.12 # change to the 2.6.12 source dir -$ patch -p1 < ../2.6.12-mm1 # apply the 2.6.12-mm1 patch -$ cd .. -$ mv linux-2.6.12 linux-2.6.12-mm1 # rename the source appropriately - -# moving from 2.6.12-mm1 to 2.6.13-rc3-mm3 -$ cd ~/linux-2.6.12-mm1 -$ patch -p1 -R < ../2.6.12-mm1 # revert the 2.6.12-mm1 patch - # we now have a 2.6.12 source -$ patch -p1 < ../patch-2.6.13-rc3 # apply the 2.6.13-rc3 patch - # we now have a 2.6.13-rc3 source -$ patch -p1 < ../2.6.13-rc3-mm3 # apply the 2.6.13-rc3-mm3 patch -$ cd .. -$ mv linux-2.6.12-mm1 linux-2.6.13-rc3-mm3 # rename the source dir - - -This concludes this list of explanations of the various kernel trees. -I hope you are now clear on how to apply the various patches and help testing -the kernel. - -Thank you's to Randy Dunlap, Rolf Eike Beer, Linus Torvalds, Bodo Eggert, -Johannes Stezenbach, Grant Coady, Pavel Machek and others that I may have -forgotten for their reviews and contributions to this document. - diff --git a/Documentation/development-process/patches/SubmittingPatches b/Documentation/development-process/patches/SubmittingPatches new file mode 100644 index 0000000..8cd0e1e --- /dev/null +++ b/Documentation/development-process/patches/SubmittingPatches @@ -0,0 +1,743 @@ + + How to Get Your Change Into the Linux Kernel + or + Care And Operation Of Your Linus Torvalds + + + +For a person or company who wishes to submit a change to the Linux +kernel, the process can sometimes be daunting if you're not familiar +with "the system." This text is a collection of suggestions which +can greatly increase the chances of your change being accepted. + +Read Documentation/SubmitChecklist for a list of items to check +before submitting code. If you are submitting a driver, also read +Documentation/SubmittingDrivers. + + + +-------------------------------------------- +SECTION 1 - CREATING AND SENDING YOUR CHANGE +-------------------------------------------- + + + +1) "diff -up" +------------ + +Use "diff -up" or "diff -uprN" to create patches. + +All changes to the Linux kernel occur in the form of patches, as +generated by diff(1). When creating your patch, make sure to create it +in "unified diff" format, as supplied by the '-u' argument to diff(1). +Also, please use the '-p' argument which shows which C function each +change is in - that makes the resultant diff a lot easier to read. +Patches should be based in the root kernel source directory, +not in any lower subdirectory. + +To create a patch for a single file, it is often sufficient to do: + + SRCTREE= linux-2.6 + MYFILE= drivers/net/mydriver.c + + cd $SRCTREE + cp $MYFILE $MYFILE.orig + vi $MYFILE # make your change + cd .. + diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch + +To create a patch for multiple files, you should unpack a "vanilla", +or unmodified kernel source tree, and generate a diff against your +own source tree. For example: + + MYSRC= /devel/linux-2.6 + + tar xvfz linux-2.6.12.tar.gz + mv linux-2.6.12 linux-2.6.12-vanilla + diff -uprN -X linux-2.6.12-vanilla/Documentation/dontdiff \ + linux-2.6.12-vanilla $MYSRC > /tmp/patch + +"dontdiff" is a list of files which are generated by the kernel during +the build process, and should be ignored in any diff(1)-generated +patch. The "dontdiff" file is included in the kernel tree in +2.6.12 and later. + +Make sure your patch does not include any extra files which do not +belong in a patch submission. Make sure to review your patch -after- +generated it with diff(1), to ensure accuracy. + +If your changes produce a lot of deltas, you may want to look into +splitting them into individual patches which modify things in +logical stages. This will facilitate easier reviewing by other +kernel developers, very important if you want your patch accepted. +There are a number of scripts which can aid in this: + +Quilt: +http://savannah.nongnu.org/projects/quilt + +Andrew Morton's patch scripts: +http://userweb.kernel.org/~akpm/stuff/patch-scripts.tar.gz +Instead of these scripts, quilt is the recommended patch management +tool (see above). + + + +2) Describe your changes. + +Describe the technical detail of the change(s) your patch includes. + +Be as specific as possible. The WORST descriptions possible include +things like "update driver X", "bug fix for driver X", or "this patch +includes updates for subsystem X. Please apply." + +The maintainer will thank you if you write your patch description in a +form which can be easily pulled into Linux's source code management +system, git, as a "commit log". See #15, below. + +If your description starts to get long, that's a sign that you probably +need to split up your patch. See #3, next. + +When you submit or resubmit a patch or patch series, include the +complete patch description and justification for it. Don't just +say that this is version N of the patch (series). Don't expect the +patch merger to refer back to earlier patch versions or referenced +URLs to find the patch description and put that into the patch. +I.e., the patch (series) and its description should be self-contained. +This benefits both the patch merger(s) and reviewers. Some reviewers +probably didn't even receive earlier versions of the patch. + +If the patch fixes a logged bug entry, refer to that bug entry by +number and URL. + + +3) Separate your changes. + +Separate _logical changes_ into a single patch file. + +For example, if your changes include both bug fixes and performance +enhancements for a single driver, separate those changes into two +or more patches. If your changes include an API update, and a new +driver which uses that new API, separate those into two patches. + +On the other hand, if you make a single change to numerous files, +group those changes into a single patch. Thus a single logical change +is contained within a single patch. + +If one patch depends on another patch in order for a change to be +complete, that is OK. Simply note "this patch depends on patch X" +in your patch description. + +If you cannot condense your patch set into a smaller set of patches, +then only post say 15 or so at a time and wait for review and integration. + + + +4) Style check your changes. + +Check your patch for basic style violations, details of which can be +found in Documentation/CodingStyle. Failure to do so simply wastes +the reviewers time and will get your patch rejected, probably +without even being read. + +At a minimum you should check your patches with the patch style +checker prior to submission (scripts/checkpatch.pl). You should +be able to justify all violations that remain in your patch. + + + +5) Select e-mail destination. + +Look through the MAINTAINERS file and the source code, and determine +if your change applies to a specific subsystem of the kernel, with +an assigned maintainer. If so, e-mail that person. The script +scripts/get_maintainer.pl can be very useful at this step. + +If no maintainer is listed, or the maintainer does not respond, send +your patch to the primary Linux kernel developer's mailing list, +linux-kernel@vger.kernel.org. Most kernel developers monitor this +e-mail list, and can comment on your changes. + + +Do not send more than 15 patches at once to the vger mailing lists!!! + + +Linus Torvalds is the final arbiter of all changes accepted into the +Linux kernel. His e-mail address is . +He gets a lot of e-mail, so typically you should do your best to -avoid- +sending him e-mail. + +Patches which are bug fixes, are "obvious" changes, or similarly +require little discussion should be sent or CC'd to Linus. Patches +which require discussion or do not have a clear advantage should +usually be sent first to linux-kernel. Only after the patch is +discussed should the patch then be submitted to Linus. + + + +6) Select your CC (e-mail carbon copy) list. + +Unless you have a reason NOT to do so, CC linux-kernel@vger.kernel.org. + +Other kernel developers besides Linus need to be aware of your change, +so that they may comment on it and offer code review and suggestions. +linux-kernel is the primary Linux kernel developer mailing list. +Other mailing lists are available for specific subsystems, such as +USB, framebuffer devices, the VFS, the SCSI subsystem, etc. See the +MAINTAINERS file for a mailing list that relates specifically to +your change. + +Majordomo lists of VGER.KERNEL.ORG at: + + +If changes affect userland-kernel interfaces, please send +the MAN-PAGES maintainer (as listed in the MAINTAINERS file) +a man-pages patch, or at least a notification of the change, +so that some information makes its way into the manual pages. + +Even if the maintainer did not respond in step #5, make sure to ALWAYS +copy the maintainer when you change their code. + +For small patches you may want to CC the Trivial Patch Monkey +trivial@kernel.org which collects "trivial" patches. Have a look +into the MAINTAINERS file for its current manager. +Trivial patches must qualify for one of the following rules: + Spelling fixes in documentation + Spelling fixes which could break grep(1) + Warning fixes (cluttering with useless warnings is bad) + Compilation fixes (only if they are actually correct) + Runtime fixes (only if they actually fix things) + Removing use of deprecated functions/macros (eg. check_region) + Contact detail and documentation fixes + Non-portable code replaced by portable code (even in arch-specific, + since people copy, as long as it's trivial) + Any fix by the author/maintainer of the file (ie. patch monkey + in re-transmission mode) + + + +7) No MIME, no links, no compression, no attachments. Just plain text. + +Linus and other kernel developers need to be able to read and comment +on the changes you are submitting. It is important for a kernel +developer to be able to "quote" your changes, using standard e-mail +tools, so that they may comment on specific portions of your code. + +For this reason, all patches should be submitting e-mail "inline". +WARNING: Be wary of your editor's word-wrap corrupting your patch, +if you choose to cut-n-paste your patch. + +Do not attach the patch as a MIME attachment, compressed or not. +Many popular e-mail applications will not always transmit a MIME +attachment as plain text, making it impossible to comment on your +code. A MIME attachment also takes Linus a bit more time to process, +decreasing the likelihood of your MIME-attached change being accepted. + +Exception: If your mailer is mangling patches then someone may ask +you to re-send them using MIME. + +See Documentation/email-clients.txt for hints about configuring +your e-mail client so that it sends your patches untouched. + +8) E-mail size. + +When sending patches to Linus, always follow step #7. + +Large changes are not appropriate for mailing lists, and some +maintainers. If your patch, uncompressed, exceeds 300 kB in size, +it is preferred that you store your patch on an Internet-accessible +server, and provide instead a URL (link) pointing to your patch. + + + +9) Name your kernel version. + +It is important to note, either in the subject line or in the patch +description, the kernel version to which this patch applies. + +If the patch does not apply cleanly to the latest kernel version, +Linus will not apply it. + + + +10) Don't get discouraged. Re-submit. + +After you have submitted your change, be patient and wait. If Linus +likes your change and applies it, it will appear in the next version +of the kernel that he releases. + +However, if your change doesn't appear in the next version of the +kernel, there could be any number of reasons. It's YOUR job to +narrow down those reasons, correct what was wrong, and submit your +updated change. + +It is quite common for Linus to "drop" your patch without comment. +That's the nature of the system. If he drops your patch, it could be +due to +* Your patch did not apply cleanly to the latest kernel version. +* Your patch was not sufficiently discussed on linux-kernel. +* A style issue (see section 2). +* An e-mail formatting issue (re-read this section). +* A technical problem with your change. +* He gets tons of e-mail, and yours got lost in the shuffle. +* You are being annoying. + +When in doubt, solicit comments on linux-kernel mailing list. + + + +11) Include PATCH in the subject + +Due to high e-mail traffic to Linus, and to linux-kernel, it is common +convention to prefix your subject line with [PATCH]. This lets Linus +and other kernel developers more easily distinguish patches from other +e-mail discussions. + + + +12) Sign your work + +To improve tracking of who did what, especially with patches that can +percolate to their final resting place in the kernel through several +layers of maintainers, we've introduced a "sign-off" procedure on +patches that are being emailed around. + +The sign-off is a simple line at the end of the explanation for the +patch, which certifies that you wrote it or otherwise have the right to +pass it on as an open-source patch. The rules are pretty simple: if you +can certify the below: + + Developer's Certificate of Origin 1.1 + + By making a contribution to this project, I certify that: + + (a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + + (b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + + (c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + + (d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. + +then you just add a line saying + + Signed-off-by: Random J Developer + +using your real name (sorry, no pseudonyms or anonymous contributions.) + +Some people also put extra tags at the end. They'll just be ignored for +now, but you can do this to mark internal company procedures or just +point out some special detail about the sign-off. + +If you are a subsystem or branch maintainer, sometimes you need to slightly +modify patches you receive in order to merge them, because the code is not +exactly the same in your tree and the submitters'. If you stick strictly to +rule (c), you should ask the submitter to rediff, but this is a totally +counter-productive waste of time and energy. Rule (b) allows you to adjust +the code, but then it is very impolite to change one submitter's code and +make him endorse your bugs. To solve this problem, it is recommended that +you add a line between the last Signed-off-by header and yours, indicating +the nature of your changes. While there is nothing mandatory about this, it +seems like prepending the description with your mail and/or name, all +enclosed in square brackets, is noticeable enough to make it obvious that +you are responsible for last-minute changes. Example : + + Signed-off-by: Random J Developer + [lucky@maintainer.example.org: struct foo moved from foo.c to foo.h] + Signed-off-by: Lucky K Maintainer + +This practise is particularly helpful if you maintain a stable branch and +want at the same time to credit the author, track changes, merge the fix, +and protect the submitter from complaints. Note that under no circumstances +can you change the author's identity (the From header), as it is the one +which appears in the changelog. + +Special note to back-porters: It seems to be a common and useful practise +to insert an indication of the origin of a patch at the top of the commit +message (just after the subject line) to facilitate tracking. For instance, +here's what we see in 2.6-stable : + + Date: Tue May 13 19:10:30 2008 +0000 + + SCSI: libiscsi regression in 2.6.25: fix nop timer handling + + commit 4cf1043593db6a337f10e006c23c69e5fc93e722 upstream + +And here's what appears in 2.4 : + + Date: Tue May 13 22:12:27 2008 +0200 + + wireless, airo: waitbusy() won't delay + + [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a] + +Whatever the format, this information provides a valuable help to people +tracking your trees, and to people trying to trouble-shoot bugs in your +tree. + + +13) When to use Acked-by: and Cc: + +The Signed-off-by: tag indicates that the signer was involved in the +development of the patch, or that he/she was in the patch's delivery path. + +If a person was not directly involved in the preparation or handling of a +patch but wishes to signify and record their approval of it then they can +arrange to have an Acked-by: line added to the patch's changelog. + +Acked-by: is often used by the maintainer of the affected code when that +maintainer neither contributed to nor forwarded the patch. + +Acked-by: is not as formal as Signed-off-by:. It is a record that the acker +has at least reviewed the patch and has indicated acceptance. Hence patch +mergers will sometimes manually convert an acker's "yep, looks good to me" +into an Acked-by:. + +Acked-by: does not necessarily indicate acknowledgement of the entire patch. +For example, if a patch affects multiple subsystems and has an Acked-by: from +one subsystem maintainer then this usually indicates acknowledgement of just +the part which affects that maintainer's code. Judgement should be used here. +When in doubt people should refer to the original discussion in the mailing +list archives. + +If a person has had the opportunity to comment on a patch, but has not +provided such comments, you may optionally add a "Cc:" tag to the patch. +This is the only tag which might be added without an explicit action by the +person it names. This tag documents that potentially interested parties +have been included in the discussion + + +14) Using Reported-by:, Tested-by:, Reviewed-by: and Suggested-by: + +If this patch fixes a problem reported by somebody else, consider adding a +Reported-by: tag to credit the reporter for their contribution. Please +note that this tag should not be added without the reporter's permission, +especially if the problem was not reported in a public forum. That said, +if we diligently credit our bug reporters, they will, hopefully, be +inspired to help us again in the future. + +A Tested-by: tag indicates that the patch has been successfully tested (in +some environment) by the person named. This tag informs maintainers that +some testing has been performed, provides a means to locate testers for +future patches, and ensures credit for the testers. + +Reviewed-by:, instead, indicates that the patch has been reviewed and found +acceptable according to the Reviewer's Statement: + + Reviewer's statement of oversight + + By offering my Reviewed-by: tag, I state that: + + (a) I have carried out a technical review of this patch to + evaluate its appropriateness and readiness for inclusion into + the mainline kernel. + + (b) Any problems, concerns, or questions relating to the patch + have been communicated back to the submitter. I am satisfied + with the submitter's response to my comments. + + (c) While there may be things that could be improved with this + submission, I believe that it is, at this time, (1) a + worthwhile modification to the kernel, and (2) free of known + issues which would argue against its inclusion. + + (d) While I have reviewed the patch and believe it to be sound, I + do not (unless explicitly stated elsewhere) make any + warranties or guarantees that it will achieve its stated + purpose or function properly in any given situation. + +A Reviewed-by tag is a statement of opinion that the patch is an +appropriate modification of the kernel without any remaining serious +technical issues. Any interested reviewer (who has done the work) can +offer a Reviewed-by tag for a patch. This tag serves to give credit to +reviewers and to inform maintainers of the degree of review which has been +done on the patch. Reviewed-by: tags, when supplied by reviewers known to +understand the subject area and to perform thorough reviews, will normally +increase the likelihood of your patch getting into the kernel. + +A Suggested-by: tag indicates that the patch idea is suggested by the person +named and ensures credit to the person for the idea. Please note that this +tag should not be added without the reporter's permission, especially if the +idea was not posted in a public forum. That said, if we diligently credit our +idea reporters, they will, hopefully, be inspired to help us again in the +future. + + +15) The canonical patch format + +The canonical patch subject line is: + + Subject: [PATCH 001/123] subsystem: summary phrase + +The canonical patch message body contains the following: + + - A "from" line specifying the patch author. + + - An empty line. + + - The body of the explanation, which will be copied to the + permanent changelog to describe this patch. + + - The "Signed-off-by:" lines, described above, which will + also go in the changelog. + + - A marker line containing simply "---". + + - Any additional comments not suitable for the changelog. + + - The actual patch (diff output). + +The Subject line format makes it very easy to sort the emails +alphabetically by subject line - pretty much any email reader will +support that - since because the sequence number is zero-padded, +the numerical and alphabetic sort is the same. + +The "subsystem" in the email's Subject should identify which +area or subsystem of the kernel is being patched. + +The "summary phrase" in the email's Subject should concisely +describe the patch which that email contains. The "summary +phrase" should not be a filename. Do not use the same "summary +phrase" for every patch in a whole patch series (where a "patch +series" is an ordered sequence of multiple, related patches). + +Bear in mind that the "summary phrase" of your email becomes a +globally-unique identifier for that patch. It propagates all the way +into the git changelog. The "summary phrase" may later be used in +developer discussions which refer to the patch. People will want to +google for the "summary phrase" to read discussion regarding that +patch. It will also be the only thing that people may quickly see +when, two or three months later, they are going through perhaps +thousands of patches using tools such as "gitk" or "git log +--oneline". + +For these reasons, the "summary" must be no more than 70-75 +characters, and it must describe both what the patch changes, as well +as why the patch might be necessary. It is challenging to be both +succinct and descriptive, but that is what a well-written summary +should do. + +The "summary phrase" may be prefixed by tags enclosed in square +brackets: "Subject: [PATCH tag] ". The tags are not +considered part of the summary phrase, but describe how the patch +should be treated. Common tags might include a version descriptor if +the multiple versions of the patch have been sent out in response to +comments (i.e., "v1, v2, v3"), or "RFC" to indicate a request for +comments. If there are four patches in a patch series the individual +patches may be numbered like this: 1/4, 2/4, 3/4, 4/4. This assures +that developers understand the order in which the patches should be +applied and that they have reviewed or applied all of the patches in +the patch series. + +A couple of example Subjects: + + Subject: [patch 2/5] ext2: improve scalability of bitmap searching + Subject: [PATCHv2 001/207] x86: fix eflags tracking + +The "from" line must be the very first line in the message body, +and has the form: + + From: Original Author + +The "from" line specifies who will be credited as the author of the +patch in the permanent changelog. If the "from" line is missing, +then the "From:" line from the email header will be used to determine +the patch author in the changelog. + +The explanation body will be committed to the permanent source +changelog, so should make sense to a competent reader who has long +since forgotten the immediate details of the discussion that might +have led to this patch. Including symptoms of the failure which the +patch addresses (kernel log messages, oops messages, etc.) is +especially useful for people who might be searching the commit logs +looking for the applicable patch. If a patch fixes a compile failure, +it may not be necessary to include _all_ of the compile failures; just +enough that it is likely that someone searching for the patch can find +it. As in the "summary phrase", it is important to be both succinct as +well as descriptive. + +The "---" marker line serves the essential purpose of marking for patch +handling tools where the changelog message ends. + +One good use for the additional comments after the "---" marker is for +a diffstat, to show what files have changed, and the number of +inserted and deleted lines per file. A diffstat is especially useful +on bigger patches. Other comments relevant only to the moment or the +maintainer, not suitable for the permanent changelog, should also go +here. A good example of such comments might be "patch changelogs" +which describe what has changed between the v1 and v2 version of the +patch. + +If you are going to include a diffstat after the "---" marker, please +use diffstat options "-p 1 -w 70" so that filenames are listed from +the top of the kernel source tree and don't use too much horizontal +space (easily fit in 80 columns, maybe with some indentation). + +See more details on the proper patch format in the following +references. + + +16) Sending "git pull" requests (from Linus emails) + +Please write the git repo address and branch name alone on the same line +so that I can't even by mistake pull from the wrong branch, and so +that a triple-click just selects the whole thing. + +So the proper format is something along the lines of: + + "Please pull from + + git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus + + to get these changes:" + +so that I don't have to hunt-and-peck for the address and inevitably +get it wrong (actually, I've only gotten it wrong a few times, and +checking against the diffstat tells me when I get it wrong, but I'm +just a lot more comfortable when I don't have to "look for" the right +thing to pull, and double-check that I have the right branch-name). + + +Please use "git diff -M --stat --summary" to generate the diffstat: +the -M enables rename detection, and the summary enables a summary of +new/deleted or renamed files. + +With rename detection, the statistics are rather different [...] +because git will notice that a fair number of the changes are renames. + +----------------------------------- +SECTION 2 - HINTS, TIPS, AND TRICKS +----------------------------------- + +This section lists many of the common "rules" associated with code +submitted to the kernel. There are always exceptions... but you must +have a really good reason for doing so. You could probably call this +section Linus Computer Science 101. + + + +1) Read Documentation/CodingStyle + +Nuff said. If your code deviates too much from this, it is likely +to be rejected without further review, and without comment. + +One significant exception is when moving code from one file to +another -- in this case you should not modify the moved code at all in +the same patch which moves it. This clearly delineates the act of +moving the code and your changes. This greatly aids review of the +actual differences and allows tools to better track the history of +the code itself. + +Check your patches with the patch style checker prior to submission +(scripts/checkpatch.pl). The style checker should be viewed as +a guide not as the final word. If your code looks better with +a violation then its probably best left alone. + +The checker reports at three levels: + - ERROR: things that are very likely to be wrong + - WARNING: things requiring careful review + - CHECK: things requiring thought + +You should be able to justify all violations that remain in your +patch. + + + +2) #ifdefs are ugly + +Code cluttered with ifdefs is difficult to read and maintain. Don't do +it. Instead, put your ifdefs in a header, and conditionally define +'static inline' functions, or macros, which are used in the code. +Let the compiler optimize away the "no-op" case. + +Simple example, of poor code: + + dev = alloc_etherdev (sizeof(struct funky_private)); + if (!dev) + return -ENODEV; + #ifdef CONFIG_NET_FUNKINESS + init_funky_net(dev); + #endif + +Cleaned-up example: + +(in header) + #ifndef CONFIG_NET_FUNKINESS + static inline void init_funky_net (struct net_device *d) {} + #endif + +(in the code itself) + dev = alloc_etherdev (sizeof(struct funky_private)); + if (!dev) + return -ENODEV; + init_funky_net(dev); + + + +3) 'static inline' is better than a macro + +Static inline functions are greatly preferred over macros. +They provide type safety, have no length limitations, no formatting +limitations, and under gcc they are as cheap as macros. + +Macros should only be used for cases where a static inline is clearly +suboptimal [there are a few, isolated cases of this in fast paths], +or where it is impossible to use a static inline function [such as +string-izing]. + +'static inline' is preferred over 'static __inline__', 'extern inline', +and 'extern __inline__'. + + + +4) Don't over-design. + +Don't try to anticipate nebulous future cases which may or may not +be useful: "Make it as simple as you can, and no simpler." + + + +---------------------- +SECTION 3 - REFERENCES +---------------------- + +Andrew Morton, "The perfect patch" (tpp). + Documentation/development-process/patches/The-Perfect-Patch.txt + +Jeff Garzik, "Linux kernel patch submission format". + Documentation/development-process/patches/Patch-Submission-Format.txt + +Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". + + + + + + +NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! + + +Kernel Documentation/CodingStyle: + + +Linus Torvalds's mail on the canonical patch format: + + +Andi Kleen, "On submitting kernel patches" + Some strategies to get difficult or controversial changes in. + http://halobates.de/on-submitting-patches.pdf + +-- diff --git a/Documentation/development-process/patches/applying-patches.txt b/Documentation/development-process/patches/applying-patches.txt new file mode 100644 index 0000000..a083ba3 --- /dev/null +++ b/Documentation/development-process/patches/applying-patches.txt @@ -0,0 +1,454 @@ + + Applying Patches To The Linux Kernel + ------------------------------------ + + Original by: Jesper Juhl, August 2005 + Last update: 2006-01-05 + + +A frequently asked question on the Linux Kernel Mailing List is how to apply +a patch to the kernel or, more specifically, what base kernel a patch for +one of the many trees/branches should be applied to. Hopefully this document +will explain this to you. + +In addition to explaining how to apply and revert patches, a brief +description of the different kernel trees (and examples of how to apply +their specific patches) is also provided. + + +What is a patch? +--- + A patch is a small text document containing a delta of changes between two +different versions of a source tree. Patches are created with the `diff' +program. +To correctly apply a patch you need to know what base it was generated from +and what new version the patch will change the source tree into. These +should both be present in the patch file metadata or be possible to deduce +from the filename. + + +How do I apply or revert a patch? +--- + You apply a patch with the `patch' program. The patch program reads a diff +(or patch) file and makes the changes to the source tree described in it. + +Patches for the Linux kernel are generated relative to the parent directory +holding the kernel source dir. + +This means that paths to files inside the patch file contain the name of the +kernel source directories it was generated against (or some other directory +names like "a/" and "b/"). +Since this is unlikely to match the name of the kernel source dir on your +local machine (but is often useful info to see what version an otherwise +unlabeled patch was generated against) you should change into your kernel +source directory and then strip the first element of the path from filenames +in the patch file when applying it (the -p1 argument to `patch' does this). + +To revert a previously applied patch, use the -R argument to patch. +So, if you applied a patch like this: + patch -p1 < ../patch-x.y.z + +You can revert (undo) it like this: + patch -R -p1 < ../patch-x.y.z + + +How do I feed a patch/diff file to `patch'? +--- + This (as usual with Linux and other UNIX like operating systems) can be +done in several different ways. +In all the examples below I feed the file (in uncompressed form) to patch +via stdin using the following syntax: + patch -p1 < path/to/patch-x.y.z + +If you just want to be able to follow the examples below and don't want to +know of more than one way to use patch, then you can stop reading this +section here. + +Patch can also get the name of the file to use via the -i argument, like +this: + patch -p1 -i path/to/patch-x.y.z + +If your patch file is compressed with gzip or bzip2 and you don't want to +uncompress it before applying it, then you can feed it to patch like this +instead: + zcat path/to/patch-x.y.z.gz | patch -p1 + bzcat path/to/patch-x.y.z.bz2 | patch -p1 + +If you wish to uncompress the patch file by hand first before applying it +(what I assume you've done in the examples below), then you simply run +gunzip or bunzip2 on the file -- like this: + gunzip patch-x.y.z.gz + bunzip2 patch-x.y.z.bz2 + +Which will leave you with a plain text patch-x.y.z file that you can feed to +patch via stdin or the -i argument, as you prefer. + +A few other nice arguments for patch are -s which causes patch to be silent +except for errors which is nice to prevent errors from scrolling out of the +screen too fast, and --dry-run which causes patch to just print a listing of +what would happen, but doesn't actually make any changes. Finally --verbose +tells patch to print more information about the work being done. + + +Common errors when patching +--- + When patch applies a patch file it attempts to verify the sanity of the +file in different ways. +Checking that the file looks like a valid patch file & checking the code +around the bits being modified matches the context provided in the patch are +just two of the basic sanity checks patch does. + +If patch encounters something that doesn't look quite right it has two +options. It can either refuse to apply the changes and abort or it can try +to find a way to make the patch apply with a few minor changes. + +One example of something that's not 'quite right' that patch will attempt to +fix up is if all the context matches, the lines being changed match, but the +line numbers are different. This can happen, for example, if the patch makes +a change in the middle of the file but for some reasons a few lines have +been added or removed near the beginning of the file. In that case +everything looks good it has just moved up or down a bit, and patch will +usually adjust the line numbers and apply the patch. + +Whenever patch applies a patch that it had to modify a bit to make it fit +it'll tell you about it by saying the patch applied with 'fuzz'. +You should be wary of such changes since even though patch probably got it +right it doesn't /always/ get it right, and the result will sometimes be +wrong. + +When patch encounters a change that it can't fix up with fuzz it rejects it +outright and leaves a file with a .rej extension (a reject file). You can +read this file to see exactly what change couldn't be applied, so you can +go fix it up by hand if you wish. + +If you don't have any third-party patches applied to your kernel source, but +only patches from kernel.org and you apply the patches in the correct order, +and have made no modifications yourself to the source files, then you should +never see a fuzz or reject message from patch. If you do see such messages +anyway, then there's a high risk that either your local source tree or the +patch file is corrupted in some way. In that case you should probably try +re-downloading the patch and if things are still not OK then you'd be advised +to start with a fresh tree downloaded in full from kernel.org. + +Let's look a bit more at some of the messages patch can produce. + +If patch stops and presents a "File to patch:" prompt, then patch could not +find a file to be patched. Most likely you forgot to specify -p1 or you are +in the wrong directory. Less often, you'll find patches that need to be +applied with -p0 instead of -p1 (reading the patch file should reveal if +this is the case -- if so, then this is an error by the person who created +the patch but is not fatal). + +If you get "Hunk #2 succeeded at 1887 with fuzz 2 (offset 7 lines)." or a +message similar to that, then it means that patch had to adjust the location +of the change (in this example it needed to move 7 lines from where it +expected to make the change to make it fit). +The resulting file may or may not be OK, depending on the reason the file +was different than expected. +This often happens if you try to apply a patch that was generated against a +different kernel version than the one you are trying to patch. + +If you get a message like "Hunk #3 FAILED at 2387.", then it means that the +patch could not be applied correctly and the patch program was unable to +fuzz its way through. This will generate a .rej file with the change that +caused the patch to fail and also a .orig file showing you the original +content that couldn't be changed. + +If you get "Reversed (or previously applied) patch detected! Assume -R? [n]" +then patch detected that the change contained in the patch seems to have +already been made. +If you actually did apply this patch previously and you just re-applied it +in error, then just say [n]o and abort this patch. If you applied this patch +previously and actually intended to revert it, but forgot to specify -R, +then you can say [y]es here to make patch revert it for you. +This can also happen if the creator of the patch reversed the source and +destination directories when creating the patch, and in that case reverting +the patch will in fact apply it. + +A message similar to "patch: **** unexpected end of file in patch" or "patch +unexpectedly ends in middle of line" means that patch could make no sense of +the file you fed to it. Either your download is broken, you tried to feed +patch a compressed patch file without uncompressing it first, or the patch +file that you are using has been mangled by a mail client or mail transfer +agent along the way somewhere, e.g., by splitting a long line into two lines. +Often these warnings can easily be fixed by joining (concatenating) the +two lines that had been split. + +As I already mentioned above, these errors should never happen if you apply +a patch from kernel.org to the correct version of an unmodified source tree. +So if you get these errors with kernel.org patches then you should probably +assume that either your patch file or your tree is broken and I'd advise you +to start over with a fresh download of a full kernel tree and the patch you +wish to apply. + + +Are there any alternatives to `patch'? +--- + Yes there are alternatives. + + You can use the `interdiff' program (http://cyberelk.net/tim/patchutils/) to +generate a patch representing the differences between two patches and then +apply the result. +This will let you move from something like 2.6.12.2 to 2.6.12.3 in a single +step. The -z flag to interdiff will even let you feed it patches in gzip or +bzip2 compressed form directly without the use of zcat or bzcat or manual +decompression. + +Here's how you'd go from 2.6.12.2 to 2.6.12.3 in a single step: + interdiff -z ../patch-2.6.12.2.bz2 ../patch-2.6.12.3.gz | patch -p1 + +Although interdiff may save you a step or two you are generally advised to +do the additional steps since interdiff can get things wrong in some cases. + + Another alternative is `ketchup', which is a python script for automatic +downloading and applying of patches (http://www.selenic.com/ketchup/). + + Other nice tools are diffstat, which shows a summary of changes made by a +patch; lsdiff, which displays a short listing of affected files in a patch +file, along with (optionally) the line numbers of the start of each patch; +and grepdiff, which displays a list of the files modified by a patch where +the patch contains a given regular expression. + + +Where can I download the patches? +--- + The patches are available at http://kernel.org/ +Most recent patches are linked from the front page, but they also have +specific homes. + +The 2.6.x.y (-stable) and 2.6.x patches live at + ftp://ftp.kernel.org/pub/linux/kernel/v2.6/ + +The -rc patches live at + ftp://ftp.kernel.org/pub/linux/kernel/v2.6/testing/ + +The -git patches live at + ftp://ftp.kernel.org/pub/linux/kernel/v2.6/snapshots/ + +The -mm kernels live at + ftp://ftp.kernel.org/pub/linux/kernel/people/akpm/patches/2.6/ + +In place of ftp.kernel.org you can use ftp.cc.kernel.org, where cc is a +country code. This way you'll be downloading from a mirror site that's most +likely geographically closer to you, resulting in faster downloads for you, +less bandwidth used globally and less load on the main kernel.org servers -- +these are good things, so do use mirrors when possible. + + +The 2.6.x kernels +--- + These are the base stable releases released by Linus. The highest numbered +release is the most recent. + +If regressions or other serious flaws are found, then a -stable fix patch +will be released (see below) on top of this base. Once a new 2.6.x base +kernel is released, a patch is made available that is a delta between the +previous 2.6.x kernel and the new one. + +To apply a patch moving from 2.6.11 to 2.6.12, you'd do the following (note +that such patches do *NOT* apply on top of 2.6.x.y kernels but on top of the +base 2.6.x kernel -- if you need to move from 2.6.x.y to 2.6.x+1 you need to +first revert the 2.6.x.y patch). + +Here are some examples: + +# moving from 2.6.11 to 2.6.12 +$ cd ~/linux-2.6.11 # change to kernel source dir +$ patch -p1 < ../patch-2.6.12 # apply the 2.6.12 patch +$ cd .. +$ mv linux-2.6.11 linux-2.6.12 # rename source dir + +# moving from 2.6.11.1 to 2.6.12 +$ cd ~/linux-2.6.11.1 # change to kernel source dir +$ patch -p1 -R < ../patch-2.6.11.1 # revert the 2.6.11.1 patch + # source dir is now 2.6.11 +$ patch -p1 < ../patch-2.6.12 # apply new 2.6.12 patch +$ cd .. +$ mv linux-2.6.11.1 linux-2.6.12 # rename source dir + + +The 2.6.x.y kernels +--- + Kernels with 4-digit versions are -stable kernels. They contain small(ish) +critical fixes for security problems or significant regressions discovered +in a given 2.6.x kernel. + +This is the recommended branch for users who want the most recent stable +kernel and are not interested in helping test development/experimental +versions. + +If no 2.6.x.y kernel is available, then the highest numbered 2.6.x kernel is +the current stable kernel. + + note: the -stable team usually do make incremental patches available as well + as patches against the latest mainline release, but I only cover the + non-incremental ones below. The incremental ones can be found at + ftp://ftp.kernel.org/pub/linux/kernel/v2.6/incr/ + +These patches are not incremental, meaning that for example the 2.6.12.3 +patch does not apply on top of the 2.6.12.2 kernel source, but rather on top +of the base 2.6.12 kernel source . +So, in order to apply the 2.6.12.3 patch to your existing 2.6.12.2 kernel +source you have to first back out the 2.6.12.2 patch (so you are left with a +base 2.6.12 kernel source) and then apply the new 2.6.12.3 patch. + +Here's a small example: + +$ cd ~/linux-2.6.12.2 # change into the kernel source dir +$ patch -p1 -R < ../patch-2.6.12.2 # revert the 2.6.12.2 patch +$ patch -p1 < ../patch-2.6.12.3 # apply the new 2.6.12.3 patch +$ cd .. +$ mv linux-2.6.12.2 linux-2.6.12.3 # rename the kernel source dir + + +The -rc kernels +--- + These are release-candidate kernels. These are development kernels released +by Linus whenever he deems the current git (the kernel's source management +tool) tree to be in a reasonably sane state adequate for testing. + +These kernels are not stable and you should expect occasional breakage if +you intend to run them. This is however the most stable of the main +development branches and is also what will eventually turn into the next +stable kernel, so it is important that it be tested by as many people as +possible. + +This is a good branch to run for people who want to help out testing +development kernels but do not want to run some of the really experimental +stuff (such people should see the sections about -git and -mm kernels below). + +The -rc patches are not incremental, they apply to a base 2.6.x kernel, just +like the 2.6.x.y patches described above. The kernel version before the -rcN +suffix denotes the version of the kernel that this -rc kernel will eventually +turn into. +So, 2.6.13-rc5 means that this is the fifth release candidate for the 2.6.13 +kernel and the patch should be applied on top of the 2.6.12 kernel source. + +Here are 3 examples of how to apply these patches: + +# first an example of moving from 2.6.12 to 2.6.13-rc3 +$ cd ~/linux-2.6.12 # change into the 2.6.12 source dir +$ patch -p1 < ../patch-2.6.13-rc3 # apply the 2.6.13-rc3 patch +$ cd .. +$ mv linux-2.6.12 linux-2.6.13-rc3 # rename the source dir + +# now let's move from 2.6.13-rc3 to 2.6.13-rc5 +$ cd ~/linux-2.6.13-rc3 # change into the 2.6.13-rc3 dir +$ patch -p1 -R < ../patch-2.6.13-rc3 # revert the 2.6.13-rc3 patch +$ patch -p1 < ../patch-2.6.13-rc5 # apply the new 2.6.13-rc5 patch +$ cd .. +$ mv linux-2.6.13-rc3 linux-2.6.13-rc5 # rename the source dir + +# finally let's try and move from 2.6.12.3 to 2.6.13-rc5 +$ cd ~/linux-2.6.12.3 # change to the kernel source dir +$ patch -p1 -R < ../patch-2.6.12.3 # revert the 2.6.12.3 patch +$ patch -p1 < ../patch-2.6.13-rc5 # apply new 2.6.13-rc5 patch +$ cd .. +$ mv linux-2.6.12.3 linux-2.6.13-rc5 # rename the kernel source dir + + +The -git kernels +--- + These are daily snapshots of Linus' kernel tree (managed in a git +repository, hence the name). + +These patches are usually released daily and represent the current state of +Linus's tree. They are more experimental than -rc kernels since they are +generated automatically without even a cursory glance to see if they are +sane. + +-git patches are not incremental and apply either to a base 2.6.x kernel or +a base 2.6.x-rc kernel -- you can see which from their name. +A patch named 2.6.12-git1 applies to the 2.6.12 kernel source and a patch +named 2.6.13-rc3-git2 applies to the source of the 2.6.13-rc3 kernel. + +Here are some examples of how to apply these patches: + +# moving from 2.6.12 to 2.6.12-git1 +$ cd ~/linux-2.6.12 # change to the kernel source dir +$ patch -p1 < ../patch-2.6.12-git1 # apply the 2.6.12-git1 patch +$ cd .. +$ mv linux-2.6.12 linux-2.6.12-git1 # rename the kernel source dir + +# moving from 2.6.12-git1 to 2.6.13-rc2-git3 +$ cd ~/linux-2.6.12-git1 # change to the kernel source dir +$ patch -p1 -R < ../patch-2.6.12-git1 # revert the 2.6.12-git1 patch + # we now have a 2.6.12 kernel +$ patch -p1 < ../patch-2.6.13-rc2 # apply the 2.6.13-rc2 patch + # the kernel is now 2.6.13-rc2 +$ patch -p1 < ../patch-2.6.13-rc2-git3 # apply the 2.6.13-rc2-git3 patch + # the kernel is now 2.6.13-rc2-git3 +$ cd .. +$ mv linux-2.6.12-git1 linux-2.6.13-rc2-git3 # rename source dir + + +The -mm kernels +--- + These are experimental kernels released by Andrew Morton. + +The -mm tree serves as a sort of proving ground for new features and other +experimental patches. +Once a patch has proved its worth in -mm for a while Andrew pushes it on to +Linus for inclusion in mainline. + +Although it's encouraged that patches flow to Linus via the -mm tree, this +is not always enforced. +Subsystem maintainers (or individuals) sometimes push their patches directly +to Linus, even though (or after) they have been merged and tested in -mm (or +sometimes even without prior testing in -mm). + +You should generally strive to get your patches into mainline via -mm to +ensure maximum testing. + +This branch is in constant flux and contains many experimental features, a +lot of debugging patches not appropriate for mainline etc., and is the most +experimental of the branches described in this document. + +These kernels are not appropriate for use on systems that are supposed to be +stable and they are more risky to run than any of the other branches (make +sure you have up-to-date backups -- that goes for any experimental kernel but +even more so for -mm kernels). + +These kernels in addition to all the other experimental patches they contain +usually also contain any changes in the mainline -git kernels available at +the time of release. + +Testing of -mm kernels is greatly appreciated since the whole point of the +tree is to weed out regressions, crashes, data corruption bugs, build +breakage (and any other bug in general) before changes are merged into the +more stable mainline Linus tree. +But testers of -mm should be aware that breakage in this tree is more common +than in any other tree. + +The -mm kernels are not released on a fixed schedule, but usually a few -mm +kernels are released in between each -rc kernel (1 to 3 is common). +The -mm kernels apply to either a base 2.6.x kernel (when no -rc kernels +have been released yet) or to a Linus -rc kernel. + +Here are some examples of applying the -mm patches: + +# moving from 2.6.12 to 2.6.12-mm1 +$ cd ~/linux-2.6.12 # change to the 2.6.12 source dir +$ patch -p1 < ../2.6.12-mm1 # apply the 2.6.12-mm1 patch +$ cd .. +$ mv linux-2.6.12 linux-2.6.12-mm1 # rename the source appropriately + +# moving from 2.6.12-mm1 to 2.6.13-rc3-mm3 +$ cd ~/linux-2.6.12-mm1 +$ patch -p1 -R < ../2.6.12-mm1 # revert the 2.6.12-mm1 patch + # we now have a 2.6.12 source +$ patch -p1 < ../patch-2.6.13-rc3 # apply the 2.6.13-rc3 patch + # we now have a 2.6.13-rc3 source +$ patch -p1 < ../2.6.13-rc3-mm3 # apply the 2.6.13-rc3-mm3 patch +$ cd .. +$ mv linux-2.6.12-mm1 linux-2.6.13-rc3-mm3 # rename the source dir + + +This concludes this list of explanations of the various kernel trees. +I hope you are now clear on how to apply the various patches and help testing +the kernel. + +Thank you's to Randy Dunlap, Rolf Eike Beer, Linus Torvalds, Bodo Eggert, +Johannes Stezenbach, Grant Coady, Pavel Machek and others that I may have +forgotten for their reviews and contributions to this document. + -- 1.8.1.2 -- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/