diff options
Diffstat (limited to 'Documentation/SubmittingPatches')
| -rw-r--r-- | Documentation/SubmittingPatches | 201 |
1 files changed, 154 insertions, 47 deletions
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index f309d3c6221..7e9abb8a276 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -14,7 +14,10 @@ Read Documentation/SubmitChecklist for a list of items to check before submitting code. If you are submitting a driver, also read Documentation/SubmittingDrivers. - +Many of these steps describe the default behavior of the git version +control system; if you use git to prepare your patches, you'll find much +of the mechanical work done for you, though you'll still need to prepare +and document a sensible set of patches. -------------------------------------------- SECTION 1 - CREATING AND SENDING YOUR CHANGE @@ -25,7 +28,9 @@ SECTION 1 - CREATING AND SENDING YOUR CHANGE 1) "diff -up" ------------ -Use "diff -up" or "diff -uprN" to create patches. +Use "diff -up" or "diff -uprN" to create patches. git generates patches +in this form by default; if you're using git, you can skip this section +entirely. 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 @@ -60,26 +65,20 @@ own source tree. For example: "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. For earlier kernel versions, you can get it -from <http://www.xenotime.net/linux/doc/dontdiff>. +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 +If your changes produce a lot of deltas, you need to split them into +individual patches which modify things in logical stages; see section +#3. This will facilitate easier reviewing by other kernel developers, +very important if you want your patch accepted. -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). +If you're using git, "git rebase -i" can help you with this process. If +you're not using git, quilt <http://savannah.nongnu.org/projects/quilt> +is another popular alternative. @@ -91,10 +90,62 @@ 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. + +Describe your changes in imperative mood, e.g. "make xyzzy do frotz" +instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy +to do frotz", as if you are giving orders to the codebase to change +its behaviour. + +If the patch fixes a logged bug entry, refer to that bug entry by +number and URL. If the patch follows from a mailing list discussion, +give a URL to the mailing list archive; use the https://lkml.kernel.org/ +redirector with a Message-Id, to ensure that the links cannot become +stale. + +However, try to make your explanation understandable without external +resources. In addition to giving a URL to a mailing list archive or +bug, summarize the relevant points of the discussion that led to the +patch as submitted. + +If you want to refer to a specific commit, don't just refer to the +SHA-1 ID of the commit. Please also include the oneline summary of +the commit, to make it easier for reviewers to know what it is about. +Example: + + Commit e21d2170f36602ae2708 ("video: remove unnecessary + platform_set_drvdata()") removed the unnecessary + platform_set_drvdata(), but left the variable "dev" unused, + delete it. + +If your patch fixes a bug in a specific commit, e.g. you found an issue using +git-bisect, please use the 'Fixes:' tag with the first 12 characters of the +SHA-1 ID, and the one line summary. +Example: + + Fixes: e21d2170f366 ("video: remove unnecessary platform_set_drvdata()") + +The following git-config settings can be used to add a pretty format for +outputting the above style in the git log or git show commands + + [core] + abbrev = 12 + [pretty] + fixes = Fixes: %h (\"%s\") 3) Separate your changes. @@ -135,7 +186,8 @@ be able to justify all violations that remain in your patch. 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. +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, @@ -179,12 +231,13 @@ 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 #4, make sure to ALWAYS +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 managed by Jesper Juhl; which collects "trivial" -patches. Trivial patches must qualify for one of the following rules: +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) @@ -196,7 +249,6 @@ patches. Trivial patches must qualify for one of the following rules: 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) -URL: <http://www.kernel.org/pub/linux/kernel/people/juhl/trivial/> @@ -228,7 +280,7 @@ your e-mail client so that it sends your patches untouched. 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 40 kB in size, +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. @@ -288,7 +340,7 @@ 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 a open-source patch. The rules are pretty simple: if you +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 @@ -405,7 +457,14 @@ person it names. This tag documents that potentially interested parties have been included in the discussion -14) Using Tested-by: and Reviewed-by: +14) Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes: + +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 @@ -444,7 +503,20 @@ 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 liklihood of your patch getting into the kernel. +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. + +A Fixes: tag indicates that the patch fixes an issue in a previous commit. It +is used to make it easy to determine where a bug originated, which can help +review a bug fix. This tag also assists the stable kernel team in determining +which stable kernel versions should receive your fix. This is the preferred +method for indicating a bug fixed by the patch. See #2 above for more details. 15) The canonical patch format @@ -485,12 +557,33 @@ 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. +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] <summary phrase>". 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: @@ -510,19 +603,32 @@ 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. +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. -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). +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). (git +generates appropriate diffstats by default.) See more details on the proper patch format in the following references. @@ -653,19 +759,20 @@ SECTION 3 - REFERENCES ---------------------- Andrew Morton, "The perfect patch" (tpp). - <http://userweb.kernel.org/~akpm/stuff/tpp.txt> + <http://www.ozlabs.org/~akpm/stuff/tpp.txt> Jeff Garzik, "Linux kernel patch submission format". <http://linux.yyz.us/patch-format.html> Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". - <http://www.kroah.com/log/2005/03/31/> - <http://www.kroah.com/log/2005/07/08/> - <http://www.kroah.com/log/2005/10/19/> - <http://www.kroah.com/log/2006/01/11/> + <http://www.kroah.com/log/linux/maintainer.html> + <http://www.kroah.com/log/linux/maintainer-02.html> + <http://www.kroah.com/log/linux/maintainer-03.html> + <http://www.kroah.com/log/linux/maintainer-04.html> + <http://www.kroah.com/log/linux/maintainer-05.html> NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! - <http://marc.theaimsgroup.com/?l=linux-kernel&m=112112749912944&w=2> + <https://lkml.org/lkml/2005/7/11/336> Kernel Documentation/CodingStyle: <http://users.sosdg.org/~qiyong/lxr/source/Documentation/CodingStyle> @@ -674,7 +781,7 @@ Linus Torvalds's mail on the canonical patch format: <http://lkml.org/lkml/2005/4/7/183> Andi Kleen, "On submitting kernel patches" - Some strategies to get difficult or controversal changes in. + Some strategies to get difficult or controversial changes in. http://halobates.de/on-submitting-patches.pdf -- |