diff options
Diffstat (limited to 'Documentation/SubmittingPatches')
| -rw-r--r-- | Documentation/SubmittingPatches | 108 |
1 files changed, 80 insertions, 28 deletions
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 689e2371095..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. @@ -107,9 +106,46 @@ 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. +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. @@ -150,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, @@ -303,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 @@ -420,7 +457,7 @@ person it names. This tag documents that potentially interested parties have been included in the discussion -14) Using Reported-by:, 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 @@ -468,6 +505,19 @@ 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. + +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 @@ -577,7 +627,8 @@ 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). +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. @@ -708,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> @@ -729,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 -- |