diff options
Diffstat (limited to 'Documentation/SubmittingPatches')
| -rw-r--r-- | Documentation/SubmittingPatches | 72 |
1 files changed, 53 insertions, 19 deletions
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 26b1e31d5a1..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 @@ -66,19 +71,14 @@ 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. @@ -106,8 +106,21 @@ 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 @@ -119,6 +132,20 @@ Example: 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. @@ -430,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:, Reviewed-by: and Suggested-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 @@ -485,6 +512,12 @@ 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 @@ -594,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. @@ -725,7 +759,7 @@ 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> @@ -738,7 +772,7 @@ Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". <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> |