Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 1 | |
| 2 | How to Get Your Change Into the Linux Kernel |
| 3 | or |
| 4 | Care And Operation Of Your Linus Torvalds |
| 5 | |
| 6 | |
| 7 | |
| 8 | For a person or company who wishes to submit a change to the Linux |
| 9 | kernel, the process can sometimes be daunting if you're not familiar |
| 10 | with "the system." This text is a collection of suggestions which |
| 11 | can greatly increase the chances of your change being accepted. |
| 12 | |
Jonathan Corbet | d00c455 | 2014-12-23 08:54:36 -0700 | [diff] [blame] | 13 | This document contains a large number of suggestions in a relatively terse |
| 14 | format. For detailed information on how the kernel development process |
| 15 | works, see Documentation/development-process. Also, read |
| 16 | Documentation/SubmitChecklist for a list of items to check before |
| 17 | submitting code. If you are submitting a driver, also read |
Jonathan Corbet | 082bd1c | 2014-12-23 09:27:04 -0700 | [diff] [blame] | 18 | Documentation/SubmittingDrivers; for device tree binding patches, read |
| 19 | Documentation/devicetree/bindings/submitting-patches.txt. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 20 | |
Josh Triplett | 8e3072a | 2014-04-03 14:48:30 -0700 | [diff] [blame] | 21 | Many of these steps describe the default behavior of the git version |
| 22 | control system; if you use git to prepare your patches, you'll find much |
| 23 | of the mechanical work done for you, though you'll still need to prepare |
Jonathan Corbet | d00c455 | 2014-12-23 08:54:36 -0700 | [diff] [blame] | 24 | and document a sensible set of patches. In general, use of git will make |
| 25 | your life as a kernel developer easier. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 26 | |
| 27 | -------------------------------------------- |
| 28 | SECTION 1 - CREATING AND SENDING YOUR CHANGE |
| 29 | -------------------------------------------- |
| 30 | |
| 31 | |
Jonathan Corbet | 7994cc1 | 2014-12-23 08:43:41 -0700 | [diff] [blame] | 32 | 0) Obtain a current source tree |
| 33 | ------------------------------- |
| 34 | |
| 35 | If you do not have a repository with the current kernel source handy, use |
| 36 | git to obtain one. You'll want to start with the mainline repository, |
| 37 | which can be grabbed with: |
| 38 | |
| 39 | git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git |
| 40 | |
| 41 | Note, however, that you may not want to develop against the mainline tree |
| 42 | directly. Most subsystem maintainers run their own trees and want to see |
| 43 | patches prepared against those trees. See the "T:" entry for the subsystem |
| 44 | in the MAINTAINERS file to find that tree, or simply ask the maintainer if |
| 45 | the tree is not listed there. |
| 46 | |
| 47 | It is still possible to download kernel releases via tarballs (as described |
| 48 | in the next section), but that is the hard way to do kernel development. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 49 | |
| 50 | 1) "diff -up" |
| 51 | ------------ |
| 52 | |
Jonathan Corbet | 7994cc1 | 2014-12-23 08:43:41 -0700 | [diff] [blame] | 53 | If you must generate your patches by hand, use "diff -up" or "diff -uprN" |
| 54 | to create patches. Git generates patches in this form by default; if |
| 55 | you're using git, you can skip this section entirely. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 56 | |
| 57 | All changes to the Linux kernel occur in the form of patches, as |
| 58 | generated by diff(1). When creating your patch, make sure to create it |
| 59 | in "unified diff" format, as supplied by the '-u' argument to diff(1). |
| 60 | Also, please use the '-p' argument which shows which C function each |
| 61 | change is in - that makes the resultant diff a lot easier to read. |
| 62 | Patches should be based in the root kernel source directory, |
| 63 | not in any lower subdirectory. |
| 64 | |
| 65 | To create a patch for a single file, it is often sufficient to do: |
| 66 | |
Jonathan Corbet | d00c455 | 2014-12-23 08:54:36 -0700 | [diff] [blame] | 67 | SRCTREE= linux |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 68 | MYFILE= drivers/net/mydriver.c |
| 69 | |
| 70 | cd $SRCTREE |
| 71 | cp $MYFILE $MYFILE.orig |
| 72 | vi $MYFILE # make your change |
| 73 | cd .. |
| 74 | diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch |
| 75 | |
| 76 | To create a patch for multiple files, you should unpack a "vanilla", |
| 77 | or unmodified kernel source tree, and generate a diff against your |
| 78 | own source tree. For example: |
| 79 | |
Jonathan Corbet | d00c455 | 2014-12-23 08:54:36 -0700 | [diff] [blame] | 80 | MYSRC= /devel/linux |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 81 | |
Jonathan Corbet | d00c455 | 2014-12-23 08:54:36 -0700 | [diff] [blame] | 82 | tar xvfz linux-3.19.tar.gz |
| 83 | mv linux-3.19 linux-3.19-vanilla |
| 84 | diff -uprN -X linux-3.19-vanilla/Documentation/dontdiff \ |
| 85 | linux-3.19-vanilla $MYSRC > /tmp/patch |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 86 | |
| 87 | "dontdiff" is a list of files which are generated by the kernel during |
| 88 | the build process, and should be ignored in any diff(1)-generated |
Jonathan Corbet | d00c455 | 2014-12-23 08:54:36 -0700 | [diff] [blame] | 89 | patch. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 90 | |
| 91 | Make sure your patch does not include any extra files which do not |
| 92 | belong in a patch submission. Make sure to review your patch -after- |
| 93 | generated it with diff(1), to ensure accuracy. |
| 94 | |
Josh Triplett | 8e3072a | 2014-04-03 14:48:30 -0700 | [diff] [blame] | 95 | If your changes produce a lot of deltas, you need to split them into |
| 96 | individual patches which modify things in logical stages; see section |
Sébastien Hinderer | 6e7ac7b | 2015-07-12 17:49:55 +0200 | [diff] [blame^] | 97 | #3. This will facilitate review by other kernel developers, |
Josh Triplett | 8e3072a | 2014-04-03 14:48:30 -0700 | [diff] [blame] | 98 | very important if you want your patch accepted. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 99 | |
Josh Triplett | 8e3072a | 2014-04-03 14:48:30 -0700 | [diff] [blame] | 100 | If you're using git, "git rebase -i" can help you with this process. If |
| 101 | you're not using git, quilt <http://savannah.nongnu.org/projects/quilt> |
| 102 | is another popular alternative. |
Randy Dunlap | 84da7c0 | 2005-06-28 20:45:30 -0700 | [diff] [blame] | 103 | |
| 104 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 105 | |
| 106 | 2) Describe your changes. |
Jonathan Corbet | d00c455 | 2014-12-23 08:54:36 -0700 | [diff] [blame] | 107 | ------------------------- |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 108 | |
Johannes Weiner | 7b9828d | 2014-08-05 23:32:56 -0700 | [diff] [blame] | 109 | Describe your problem. Whether your patch is a one-line bug fix or |
| 110 | 5000 lines of a new feature, there must be an underlying problem that |
| 111 | motivated you to do this work. Convince the reviewer that there is a |
| 112 | problem worth fixing and that it makes sense for them to read past the |
| 113 | first paragraph. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 114 | |
Johannes Weiner | 7b9828d | 2014-08-05 23:32:56 -0700 | [diff] [blame] | 115 | Describe user-visible impact. Straight up crashes and lockups are |
| 116 | pretty convincing, but not all bugs are that blatant. Even if the |
| 117 | problem was spotted during code review, describe the impact you think |
| 118 | it can have on users. Keep in mind that the majority of Linux |
| 119 | installations run kernels from secondary stable trees or |
| 120 | vendor/product-specific trees that cherry-pick only specific patches |
| 121 | from upstream, so include anything that could help route your change |
| 122 | downstream: provoking circumstances, excerpts from dmesg, crash |
| 123 | descriptions, performance regressions, latency spikes, lockups, etc. |
| 124 | |
| 125 | Quantify optimizations and trade-offs. If you claim improvements in |
| 126 | performance, memory consumption, stack footprint, or binary size, |
| 127 | include numbers that back them up. But also describe non-obvious |
| 128 | costs. Optimizations usually aren't free but trade-offs between CPU, |
| 129 | memory, and readability; or, when it comes to heuristics, between |
| 130 | different workloads. Describe the expected downsides of your |
| 131 | optimization so that the reviewer can weigh costs against benefits. |
| 132 | |
| 133 | Once the problem is established, describe what you are actually doing |
| 134 | about it in technical detail. It's important to describe the change |
| 135 | in plain English for the reviewer to verify that the code is behaving |
| 136 | as you intend it to. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 137 | |
Theodore Ts'o | 2ae19ac | 2009-04-16 07:44:45 -0400 | [diff] [blame] | 138 | The maintainer will thank you if you write your patch description in a |
| 139 | form which can be easily pulled into Linux's source code management |
| 140 | system, git, as a "commit log". See #15, below. |
| 141 | |
Johannes Weiner | 7b9828d | 2014-08-05 23:32:56 -0700 | [diff] [blame] | 142 | Solve only one problem per patch. If your description starts to get |
| 143 | long, that's a sign that you probably need to split up your patch. |
| 144 | See #3, next. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 145 | |
Randy Dunlap | d89b194 | 2010-08-09 17:20:21 -0700 | [diff] [blame] | 146 | When you submit or resubmit a patch or patch series, include the |
| 147 | complete patch description and justification for it. Don't just |
| 148 | say that this is version N of the patch (series). Don't expect the |
Jonathan Corbet | d00c455 | 2014-12-23 08:54:36 -0700 | [diff] [blame] | 149 | subsystem maintainer to refer back to earlier patch versions or referenced |
Randy Dunlap | d89b194 | 2010-08-09 17:20:21 -0700 | [diff] [blame] | 150 | URLs to find the patch description and put that into the patch. |
| 151 | I.e., the patch (series) and its description should be self-contained. |
Jonathan Corbet | d00c455 | 2014-12-23 08:54:36 -0700 | [diff] [blame] | 152 | This benefits both the maintainers and reviewers. Some reviewers |
Randy Dunlap | d89b194 | 2010-08-09 17:20:21 -0700 | [diff] [blame] | 153 | probably didn't even receive earlier versions of the patch. |
| 154 | |
Josh Triplett | 74a475a | 2014-04-03 14:48:28 -0700 | [diff] [blame] | 155 | Describe your changes in imperative mood, e.g. "make xyzzy do frotz" |
| 156 | instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy |
| 157 | to do frotz", as if you are giving orders to the codebase to change |
| 158 | its behaviour. |
| 159 | |
Randy Dunlap | d89b194 | 2010-08-09 17:20:21 -0700 | [diff] [blame] | 160 | If the patch fixes a logged bug entry, refer to that bug entry by |
Josh Triplett | 9547c70 | 2014-04-03 14:48:29 -0700 | [diff] [blame] | 161 | number and URL. If the patch follows from a mailing list discussion, |
| 162 | give a URL to the mailing list archive; use the https://lkml.kernel.org/ |
| 163 | redirector with a Message-Id, to ensure that the links cannot become |
| 164 | stale. |
| 165 | |
| 166 | However, try to make your explanation understandable without external |
| 167 | resources. In addition to giving a URL to a mailing list archive or |
| 168 | bug, summarize the relevant points of the discussion that led to the |
| 169 | patch as submitted. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 170 | |
Geert Uytterhoeven | 0af5270 | 2013-07-31 14:59:38 -0700 | [diff] [blame] | 171 | If you want to refer to a specific commit, don't just refer to the |
| 172 | SHA-1 ID of the commit. Please also include the oneline summary of |
| 173 | the commit, to make it easier for reviewers to know what it is about. |
| 174 | Example: |
| 175 | |
| 176 | Commit e21d2170f36602ae2708 ("video: remove unnecessary |
| 177 | platform_set_drvdata()") removed the unnecessary |
| 178 | platform_set_drvdata(), but left the variable "dev" unused, |
| 179 | delete it. |
| 180 | |
Jonathan Corbet | 7994cc1 | 2014-12-23 08:43:41 -0700 | [diff] [blame] | 181 | You should also be sure to use at least the first twelve characters of the |
| 182 | SHA-1 ID. The kernel repository holds a *lot* of objects, making |
| 183 | collisions with shorter IDs a real possibility. Bear in mind that, even if |
| 184 | there is no collision with your six-character ID now, that condition may |
| 185 | change five years from now. |
| 186 | |
Jacob Keller | 8401aa1 | 2014-06-06 14:36:39 -0700 | [diff] [blame] | 187 | If your patch fixes a bug in a specific commit, e.g. you found an issue using |
| 188 | git-bisect, please use the 'Fixes:' tag with the first 12 characters of the |
Jonathan Corbet | 7994cc1 | 2014-12-23 08:43:41 -0700 | [diff] [blame] | 189 | SHA-1 ID, and the one line summary. For example: |
Jacob Keller | 8401aa1 | 2014-06-06 14:36:39 -0700 | [diff] [blame] | 190 | |
| 191 | Fixes: e21d2170f366 ("video: remove unnecessary platform_set_drvdata()") |
| 192 | |
| 193 | The following git-config settings can be used to add a pretty format for |
| 194 | outputting the above style in the git log or git show commands |
| 195 | |
| 196 | [core] |
| 197 | abbrev = 12 |
| 198 | [pretty] |
| 199 | fixes = Fixes: %h (\"%s\") |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 200 | |
| 201 | 3) Separate your changes. |
Jonathan Corbet | d00c455 | 2014-12-23 08:54:36 -0700 | [diff] [blame] | 202 | ------------------------- |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 203 | |
Jonathan Corbet | d00c455 | 2014-12-23 08:54:36 -0700 | [diff] [blame] | 204 | Separate each _logical change_ into a separate patch. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 205 | |
| 206 | For example, if your changes include both bug fixes and performance |
| 207 | enhancements for a single driver, separate those changes into two |
| 208 | or more patches. If your changes include an API update, and a new |
| 209 | driver which uses that new API, separate those into two patches. |
| 210 | |
| 211 | On the other hand, if you make a single change to numerous files, |
| 212 | group those changes into a single patch. Thus a single logical change |
| 213 | is contained within a single patch. |
| 214 | |
Jonathan Corbet | d00c455 | 2014-12-23 08:54:36 -0700 | [diff] [blame] | 215 | The point to remember is that each patch should make an easily understood |
| 216 | change that can be verified by reviewers. Each patch should be justifiable |
| 217 | on its own merits. |
| 218 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 219 | If one patch depends on another patch in order for a change to be |
| 220 | complete, that is OK. Simply note "this patch depends on patch X" |
| 221 | in your patch description. |
| 222 | |
Jonathan Corbet | 7994cc1 | 2014-12-23 08:43:41 -0700 | [diff] [blame] | 223 | When dividing your change into a series of patches, take special care to |
| 224 | ensure that the kernel builds and runs properly after each patch in the |
| 225 | series. Developers using "git bisect" to track down a problem can end up |
| 226 | splitting your patch series at any point; they will not thank you if you |
| 227 | introduce bugs in the middle. |
| 228 | |
Xose Vazquez Perez | 5b0ed2c | 2006-01-08 01:02:49 -0800 | [diff] [blame] | 229 | If you cannot condense your patch set into a smaller set of patches, |
| 230 | then only post say 15 or so at a time and wait for review and integration. |
| 231 | |
| 232 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 233 | |
Jonathan Corbet | 6de16eb | 2014-12-23 08:38:24 -0700 | [diff] [blame] | 234 | 4) Style-check your changes. |
| 235 | ---------------------------- |
Andy Whitcroft | 0a920b5 | 2007-06-01 00:46:48 -0700 | [diff] [blame] | 236 | |
| 237 | Check your patch for basic style violations, details of which can be |
| 238 | found in Documentation/CodingStyle. Failure to do so simply wastes |
Linus Nilsson | f56d35e | 2007-07-21 17:49:06 +0200 | [diff] [blame] | 239 | the reviewers time and will get your patch rejected, probably |
Andy Whitcroft | 0a920b5 | 2007-06-01 00:46:48 -0700 | [diff] [blame] | 240 | without even being read. |
| 241 | |
Jonathan Corbet | 6de16eb | 2014-12-23 08:38:24 -0700 | [diff] [blame] | 242 | One significant exception is when moving code from one file to |
| 243 | another -- in this case you should not modify the moved code at all in |
| 244 | the same patch which moves it. This clearly delineates the act of |
| 245 | moving the code and your changes. This greatly aids review of the |
| 246 | actual differences and allows tools to better track the history of |
| 247 | the code itself. |
Andy Whitcroft | 0a920b5 | 2007-06-01 00:46:48 -0700 | [diff] [blame] | 248 | |
Jonathan Corbet | 6de16eb | 2014-12-23 08:38:24 -0700 | [diff] [blame] | 249 | Check your patches with the patch style checker prior to submission |
| 250 | (scripts/checkpatch.pl). Note, though, that the style checker should be |
| 251 | viewed as a guide, not as a replacement for human judgment. If your code |
| 252 | looks better with a violation then its probably best left alone. |
| 253 | |
| 254 | The checker reports at three levels: |
| 255 | - ERROR: things that are very likely to be wrong |
| 256 | - WARNING: things requiring careful review |
| 257 | - CHECK: things requiring thought |
| 258 | |
| 259 | You should be able to justify all violations that remain in your |
| 260 | patch. |
Andy Whitcroft | 0a920b5 | 2007-06-01 00:46:48 -0700 | [diff] [blame] | 261 | |
| 262 | |
Jonathan Corbet | ccae861 | 2014-12-23 08:49:18 -0700 | [diff] [blame] | 263 | 5) Select the recipients for your patch. |
| 264 | ---------------------------------------- |
Andy Whitcroft | 0a920b5 | 2007-06-01 00:46:48 -0700 | [diff] [blame] | 265 | |
Jonathan Corbet | ccae861 | 2014-12-23 08:49:18 -0700 | [diff] [blame] | 266 | You should always copy the appropriate subsystem maintainer(s) on any patch |
| 267 | to code that they maintain; look through the MAINTAINERS file and the |
| 268 | source code revision history to see who those maintainers are. The |
| 269 | script scripts/get_maintainer.pl can be very useful at this step. If you |
Sébastien Hinderer | d6eff07 | 2015-07-08 21:12:32 +0200 | [diff] [blame] | 270 | cannot find a maintainer for the subsystem you are working on, Andrew |
Jonathan Corbet | ccae861 | 2014-12-23 08:49:18 -0700 | [diff] [blame] | 271 | Morton (akpm@linux-foundation.org) serves as a maintainer of last resort. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 272 | |
Jonathan Corbet | ccae861 | 2014-12-23 08:49:18 -0700 | [diff] [blame] | 273 | You should also normally choose at least one mailing list to receive a copy |
| 274 | of your patch set. linux-kernel@vger.kernel.org functions as a list of |
| 275 | last resort, but the volume on that list has caused a number of developers |
| 276 | to tune it out. Look in the MAINTAINERS file for a subsystem-specific |
| 277 | list; your patch will probably get more attention there. Please do not |
| 278 | spam unrelated lists, though. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 279 | |
Jonathan Corbet | ccae861 | 2014-12-23 08:49:18 -0700 | [diff] [blame] | 280 | Many kernel-related lists are hosted on vger.kernel.org; you can find a |
| 281 | list of them at http://vger.kernel.org/vger-lists.html. There are |
| 282 | kernel-related lists hosted elsewhere as well, though. |
Xose Vazquez Perez | 5b0ed2c | 2006-01-08 01:02:49 -0800 | [diff] [blame] | 283 | |
| 284 | Do not send more than 15 patches at once to the vger mailing lists!!! |
| 285 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 286 | Linus Torvalds is the final arbiter of all changes accepted into the |
Stefan Beller | e00bfcb | 2014-12-17 17:13:56 -0800 | [diff] [blame] | 287 | Linux kernel. His e-mail address is <torvalds@linux-foundation.org>. |
Jonathan Corbet | ccae861 | 2014-12-23 08:49:18 -0700 | [diff] [blame] | 288 | He gets a lot of e-mail, and, at this point, very few patches go through |
| 289 | Linus directly, so typically you should do your best to -avoid- |
Stefan Beller | e00bfcb | 2014-12-17 17:13:56 -0800 | [diff] [blame] | 290 | sending him e-mail. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 291 | |
Jonathan Corbet | ccae861 | 2014-12-23 08:49:18 -0700 | [diff] [blame] | 292 | If you have a patch that fixes an exploitable security bug, send that patch |
| 293 | to security@kernel.org. For severe bugs, a short embargo may be considered |
| 294 | to allow distrbutors to get the patch out to users; in such cases, |
| 295 | obviously, the patch should not be sent to any public lists. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 296 | |
Jonathan Corbet | ccae861 | 2014-12-23 08:49:18 -0700 | [diff] [blame] | 297 | Patches that fix a severe bug in a released kernel should be directed |
| 298 | toward the stable maintainers by putting a line like this: |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 299 | |
Jonathan Corbet | ccae861 | 2014-12-23 08:49:18 -0700 | [diff] [blame] | 300 | Cc: stable@vger.kernel.org |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 301 | |
Luke Dashjr | 8cda4c3 | 2015-05-14 18:58:01 +0000 | [diff] [blame] | 302 | into the sign-off area of your patch (note, NOT an email recipient). You |
| 303 | should also read Documentation/stable_kernel_rules.txt in addition to this |
| 304 | file. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 305 | |
Jonathan Corbet | ccae861 | 2014-12-23 08:49:18 -0700 | [diff] [blame] | 306 | Note, however, that some subsystem maintainers want to come to their own |
| 307 | conclusions on which patches should go to the stable trees. The networking |
| 308 | maintainer, in particular, would rather not see individual developers |
| 309 | adding lines like the above to their patches. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 310 | |
Jonathan Corbet | ccae861 | 2014-12-23 08:49:18 -0700 | [diff] [blame] | 311 | If changes affect userland-kernel interfaces, please send the MAN-PAGES |
| 312 | maintainer (as listed in the MAINTAINERS file) a man-pages patch, or at |
| 313 | least a notification of the change, so that some information makes its way |
| 314 | into the manual pages. User-space API changes should also be copied to |
| 315 | linux-api@vger.kernel.org. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 316 | |
| 317 | For small patches you may want to CC the Trivial Patch Monkey |
Markus Heidelberg | 82d27b2 | 2009-06-12 01:02:34 +0200 | [diff] [blame] | 318 | trivial@kernel.org which collects "trivial" patches. Have a look |
| 319 | into the MAINTAINERS file for its current manager. |
| 320 | Trivial patches must qualify for one of the following rules: |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 321 | Spelling fixes in documentation |
Jonathan Corbet | ccae861 | 2014-12-23 08:49:18 -0700 | [diff] [blame] | 322 | Spelling fixes for errors which could break grep(1) |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 323 | Warning fixes (cluttering with useless warnings is bad) |
| 324 | Compilation fixes (only if they are actually correct) |
| 325 | Runtime fixes (only if they actually fix things) |
Jonathan Corbet | ccae861 | 2014-12-23 08:49:18 -0700 | [diff] [blame] | 326 | Removing use of deprecated functions/macros |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 327 | Contact detail and documentation fixes |
| 328 | Non-portable code replaced by portable code (even in arch-specific, |
| 329 | since people copy, as long as it's trivial) |
Pavel Machek | 8e9cb8f | 2006-09-29 02:01:29 -0700 | [diff] [blame] | 330 | Any fix by the author/maintainer of the file (ie. patch monkey |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 331 | in re-transmission mode) |
Randy Dunlap | 84da7c0 | 2005-06-28 20:45:30 -0700 | [diff] [blame] | 332 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 333 | |
| 334 | |
Jonathan Corbet | ccae861 | 2014-12-23 08:49:18 -0700 | [diff] [blame] | 335 | 6) No MIME, no links, no compression, no attachments. Just plain text. |
Jonathan Corbet | d00c455 | 2014-12-23 08:54:36 -0700 | [diff] [blame] | 336 | ----------------------------------------------------------------------- |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 337 | |
| 338 | Linus and other kernel developers need to be able to read and comment |
| 339 | on the changes you are submitting. It is important for a kernel |
| 340 | developer to be able to "quote" your changes, using standard e-mail |
| 341 | tools, so that they may comment on specific portions of your code. |
| 342 | |
Sébastien Hinderer | bdc8921 | 2015-07-12 17:44:15 +0200 | [diff] [blame] | 343 | For this reason, all patches should be submitted by e-mail "inline". |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 344 | WARNING: Be wary of your editor's word-wrap corrupting your patch, |
| 345 | if you choose to cut-n-paste your patch. |
| 346 | |
| 347 | Do not attach the patch as a MIME attachment, compressed or not. |
| 348 | Many popular e-mail applications will not always transmit a MIME |
| 349 | attachment as plain text, making it impossible to comment on your |
| 350 | code. A MIME attachment also takes Linus a bit more time to process, |
| 351 | decreasing the likelihood of your MIME-attached change being accepted. |
| 352 | |
| 353 | Exception: If your mailer is mangling patches then someone may ask |
| 354 | you to re-send them using MIME. |
| 355 | |
Michael Opdenacker | 097091c | 2008-02-03 18:06:58 +0200 | [diff] [blame] | 356 | See Documentation/email-clients.txt for hints about configuring |
| 357 | your e-mail client so that it sends your patches untouched. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 358 | |
Jonathan Corbet | ccae861 | 2014-12-23 08:49:18 -0700 | [diff] [blame] | 359 | 7) E-mail size. |
Jonathan Corbet | d00c455 | 2014-12-23 08:54:36 -0700 | [diff] [blame] | 360 | --------------- |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 361 | |
| 362 | Large changes are not appropriate for mailing lists, and some |
Randy Dunlap | 4932be7 | 2009-10-01 15:44:06 -0700 | [diff] [blame] | 363 | maintainers. If your patch, uncompressed, exceeds 300 kB in size, |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 364 | it is preferred that you store your patch on an Internet-accessible |
Jonathan Corbet | d00c455 | 2014-12-23 08:54:36 -0700 | [diff] [blame] | 365 | server, and provide instead a URL (link) pointing to your patch. But note |
| 366 | that if your patch exceeds 300 kB, it almost certainly needs to be broken up |
| 367 | anyway. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 368 | |
Jonathan Corbet | 0eea231 | 2014-12-23 08:52:01 -0700 | [diff] [blame] | 369 | 8) Respond to review comments. |
| 370 | ------------------------------ |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 371 | |
Jonathan Corbet | 0eea231 | 2014-12-23 08:52:01 -0700 | [diff] [blame] | 372 | Your patch will almost certainly get comments from reviewers on ways in |
| 373 | which the patch can be improved. You must respond to those comments; |
| 374 | ignoring reviewers is a good way to get ignored in return. Review comments |
| 375 | or questions that do not lead to a code change should almost certainly |
| 376 | bring about a comment or changelog entry so that the next reviewer better |
| 377 | understands what is going on. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 378 | |
Jonathan Corbet | 0eea231 | 2014-12-23 08:52:01 -0700 | [diff] [blame] | 379 | Be sure to tell the reviewers what changes you are making and to thank them |
| 380 | for their time. Code review is a tiring and time-consuming process, and |
| 381 | reviewers sometimes get grumpy. Even in that case, though, respond |
| 382 | politely and address the problems they have pointed out. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 383 | |
| 384 | |
Jonathan Corbet | 0eea231 | 2014-12-23 08:52:01 -0700 | [diff] [blame] | 385 | 9) Don't get discouraged - or impatient. |
| 386 | ---------------------------------------- |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 387 | |
Jonathan Corbet | 0eea231 | 2014-12-23 08:52:01 -0700 | [diff] [blame] | 388 | After you have submitted your change, be patient and wait. Reviewers are |
| 389 | busy people and may not get to your patch right away. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 390 | |
Jonathan Corbet | 0eea231 | 2014-12-23 08:52:01 -0700 | [diff] [blame] | 391 | Once upon a time, patches used to disappear into the void without comment, |
| 392 | but the development process works more smoothly than that now. You should |
| 393 | receive comments within a week or so; if that does not happen, make sure |
| 394 | that you have sent your patches to the right place. Wait for a minimum of |
| 395 | one week before resubmitting or pinging reviewers - possibly longer during |
| 396 | busy times like merge windows. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 397 | |
| 398 | |
Jonathan Corbet | ccae861 | 2014-12-23 08:49:18 -0700 | [diff] [blame] | 399 | 10) Include PATCH in the subject |
Jonathan Corbet | d00c455 | 2014-12-23 08:54:36 -0700 | [diff] [blame] | 400 | -------------------------------- |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 401 | |
| 402 | Due to high e-mail traffic to Linus, and to linux-kernel, it is common |
| 403 | convention to prefix your subject line with [PATCH]. This lets Linus |
| 404 | and other kernel developers more easily distinguish patches from other |
| 405 | e-mail discussions. |
| 406 | |
| 407 | |
| 408 | |
Jonathan Corbet | ccae861 | 2014-12-23 08:49:18 -0700 | [diff] [blame] | 409 | 11) Sign your work |
Jonathan Corbet | d00c455 | 2014-12-23 08:54:36 -0700 | [diff] [blame] | 410 | ------------------ |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 411 | |
| 412 | To improve tracking of who did what, especially with patches that can |
| 413 | percolate to their final resting place in the kernel through several |
| 414 | layers of maintainers, we've introduced a "sign-off" procedure on |
| 415 | patches that are being emailed around. |
| 416 | |
| 417 | The sign-off is a simple line at the end of the explanation for the |
| 418 | patch, which certifies that you wrote it or otherwise have the right to |
Zac Storer | db12fb8 | 2011-08-13 12:34:45 -0700 | [diff] [blame] | 419 | pass it on as an open-source patch. The rules are pretty simple: if you |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 420 | can certify the below: |
| 421 | |
Linus Torvalds | cbd83da | 2005-06-13 17:51:55 -0700 | [diff] [blame] | 422 | Developer's Certificate of Origin 1.1 |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 423 | |
| 424 | By making a contribution to this project, I certify that: |
| 425 | |
| 426 | (a) The contribution was created in whole or in part by me and I |
| 427 | have the right to submit it under the open source license |
| 428 | indicated in the file; or |
| 429 | |
| 430 | (b) The contribution is based upon previous work that, to the best |
| 431 | of my knowledge, is covered under an appropriate open source |
| 432 | license and I have the right under that license to submit that |
| 433 | work with modifications, whether created in whole or in part |
| 434 | by me, under the same open source license (unless I am |
| 435 | permitted to submit under a different license), as indicated |
| 436 | in the file; or |
| 437 | |
| 438 | (c) The contribution was provided directly to me by some other |
| 439 | person who certified (a), (b) or (c) and I have not modified |
| 440 | it. |
| 441 | |
Stefan Beller | e00bfcb | 2014-12-17 17:13:56 -0800 | [diff] [blame] | 442 | (d) I understand and agree that this project and the contribution |
| 443 | are public and that a record of the contribution (including all |
| 444 | personal information I submit with it, including my sign-off) is |
| 445 | maintained indefinitely and may be redistributed consistent with |
| 446 | this project or the open source license(s) involved. |
Linus Torvalds | cbd83da | 2005-06-13 17:51:55 -0700 | [diff] [blame] | 447 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 448 | then you just add a line saying |
| 449 | |
Alexey Dobriyan | 9fd5559 | 2005-06-25 14:59:34 -0700 | [diff] [blame] | 450 | Signed-off-by: Random J Developer <random@developer.example.org> |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 451 | |
Greg KH | af45f32 | 2006-09-12 20:35:52 -0700 | [diff] [blame] | 452 | using your real name (sorry, no pseudonyms or anonymous contributions.) |
| 453 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 454 | Some people also put extra tags at the end. They'll just be ignored for |
| 455 | now, but you can do this to mark internal company procedures or just |
Stefan Beller | e00bfcb | 2014-12-17 17:13:56 -0800 | [diff] [blame] | 456 | point out some special detail about the sign-off. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 457 | |
Willy Tarreau | adbd588 | 2008-06-03 00:20:28 +0200 | [diff] [blame] | 458 | If you are a subsystem or branch maintainer, sometimes you need to slightly |
| 459 | modify patches you receive in order to merge them, because the code is not |
| 460 | exactly the same in your tree and the submitters'. If you stick strictly to |
| 461 | rule (c), you should ask the submitter to rediff, but this is a totally |
| 462 | counter-productive waste of time and energy. Rule (b) allows you to adjust |
| 463 | the code, but then it is very impolite to change one submitter's code and |
| 464 | make him endorse your bugs. To solve this problem, it is recommended that |
| 465 | you add a line between the last Signed-off-by header and yours, indicating |
| 466 | the nature of your changes. While there is nothing mandatory about this, it |
| 467 | seems like prepending the description with your mail and/or name, all |
| 468 | enclosed in square brackets, is noticeable enough to make it obvious that |
| 469 | you are responsible for last-minute changes. Example : |
| 470 | |
| 471 | Signed-off-by: Random J Developer <random@developer.example.org> |
| 472 | [lucky@maintainer.example.org: struct foo moved from foo.c to foo.h] |
| 473 | Signed-off-by: Lucky K Maintainer <lucky@maintainer.example.org> |
| 474 | |
Jeremiah Mahler | 305af08 | 2014-05-22 00:04:26 -0700 | [diff] [blame] | 475 | This practice is particularly helpful if you maintain a stable branch and |
Willy Tarreau | adbd588 | 2008-06-03 00:20:28 +0200 | [diff] [blame] | 476 | want at the same time to credit the author, track changes, merge the fix, |
| 477 | and protect the submitter from complaints. Note that under no circumstances |
| 478 | can you change the author's identity (the From header), as it is the one |
| 479 | which appears in the changelog. |
| 480 | |
Jeremiah Mahler | 305af08 | 2014-05-22 00:04:26 -0700 | [diff] [blame] | 481 | Special note to back-porters: It seems to be a common and useful practice |
Willy Tarreau | adbd588 | 2008-06-03 00:20:28 +0200 | [diff] [blame] | 482 | to insert an indication of the origin of a patch at the top of the commit |
| 483 | message (just after the subject line) to facilitate tracking. For instance, |
Jonathan Corbet | 7994cc1 | 2014-12-23 08:43:41 -0700 | [diff] [blame] | 484 | here's what we see in a 3.x-stable release: |
Willy Tarreau | adbd588 | 2008-06-03 00:20:28 +0200 | [diff] [blame] | 485 | |
Jonathan Corbet | 7994cc1 | 2014-12-23 08:43:41 -0700 | [diff] [blame] | 486 | Date: Tue Oct 7 07:26:38 2014 -0400 |
Willy Tarreau | adbd588 | 2008-06-03 00:20:28 +0200 | [diff] [blame] | 487 | |
Jonathan Corbet | 7994cc1 | 2014-12-23 08:43:41 -0700 | [diff] [blame] | 488 | libata: Un-break ATA blacklist |
Willy Tarreau | adbd588 | 2008-06-03 00:20:28 +0200 | [diff] [blame] | 489 | |
Jonathan Corbet | 7994cc1 | 2014-12-23 08:43:41 -0700 | [diff] [blame] | 490 | commit 1c40279960bcd7d52dbdf1d466b20d24b99176c8 upstream. |
Willy Tarreau | adbd588 | 2008-06-03 00:20:28 +0200 | [diff] [blame] | 491 | |
Jonathan Corbet | 7994cc1 | 2014-12-23 08:43:41 -0700 | [diff] [blame] | 492 | And here's what might appear in an older kernel once a patch is backported: |
Willy Tarreau | adbd588 | 2008-06-03 00:20:28 +0200 | [diff] [blame] | 493 | |
| 494 | Date: Tue May 13 22:12:27 2008 +0200 |
| 495 | |
| 496 | wireless, airo: waitbusy() won't delay |
| 497 | |
| 498 | [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a] |
| 499 | |
| 500 | Whatever the format, this information provides a valuable help to people |
Jonathan Corbet | 7994cc1 | 2014-12-23 08:43:41 -0700 | [diff] [blame] | 501 | tracking your trees, and to people trying to troubleshoot bugs in your |
Willy Tarreau | adbd588 | 2008-06-03 00:20:28 +0200 | [diff] [blame] | 502 | tree. |
| 503 | |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 504 | |
Jonathan Corbet | ccae861 | 2014-12-23 08:49:18 -0700 | [diff] [blame] | 505 | 12) When to use Acked-by: and Cc: |
Jonathan Corbet | d00c455 | 2014-12-23 08:54:36 -0700 | [diff] [blame] | 506 | --------------------------------- |
Andy Whitcroft | 0a920b5 | 2007-06-01 00:46:48 -0700 | [diff] [blame] | 507 | |
Andrew Morton | 0f44cd2 | 2007-06-08 13:46:45 -0700 | [diff] [blame] | 508 | The Signed-off-by: tag indicates that the signer was involved in the |
| 509 | development of the patch, or that he/she was in the patch's delivery path. |
| 510 | |
| 511 | If a person was not directly involved in the preparation or handling of a |
| 512 | patch but wishes to signify and record their approval of it then they can |
Jonathan Corbet | d00c455 | 2014-12-23 08:54:36 -0700 | [diff] [blame] | 513 | ask to have an Acked-by: line added to the patch's changelog. |
Andrew Morton | 0f44cd2 | 2007-06-08 13:46:45 -0700 | [diff] [blame] | 514 | |
| 515 | Acked-by: is often used by the maintainer of the affected code when that |
| 516 | maintainer neither contributed to nor forwarded the patch. |
| 517 | |
| 518 | Acked-by: is not as formal as Signed-off-by:. It is a record that the acker |
| 519 | has at least reviewed the patch and has indicated acceptance. Hence patch |
| 520 | mergers will sometimes manually convert an acker's "yep, looks good to me" |
Jonathan Corbet | d00c455 | 2014-12-23 08:54:36 -0700 | [diff] [blame] | 521 | into an Acked-by: (but note that it is usually better to ask for an |
| 522 | explicit ack). |
Andrew Morton | 0f44cd2 | 2007-06-08 13:46:45 -0700 | [diff] [blame] | 523 | |
| 524 | Acked-by: does not necessarily indicate acknowledgement of the entire patch. |
| 525 | For example, if a patch affects multiple subsystems and has an Acked-by: from |
| 526 | one subsystem maintainer then this usually indicates acknowledgement of just |
| 527 | the part which affects that maintainer's code. Judgement should be used here. |
Jonathan Corbet | ef40203 | 2008-03-28 11:22:38 -0600 | [diff] [blame] | 528 | When in doubt people should refer to the original discussion in the mailing |
Andrew Morton | 0f44cd2 | 2007-06-08 13:46:45 -0700 | [diff] [blame] | 529 | list archives. |
| 530 | |
Jonathan Corbet | ef40203 | 2008-03-28 11:22:38 -0600 | [diff] [blame] | 531 | If a person has had the opportunity to comment on a patch, but has not |
| 532 | provided such comments, you may optionally add a "Cc:" tag to the patch. |
| 533 | This is the only tag which might be added without an explicit action by the |
Jonathan Corbet | d00c455 | 2014-12-23 08:54:36 -0700 | [diff] [blame] | 534 | person it names - but it should indicate that this person was copied on the |
| 535 | patch. This tag documents that potentially interested parties |
| 536 | have been included in the discussion. |
Andrew Morton | 0f44cd2 | 2007-06-08 13:46:45 -0700 | [diff] [blame] | 537 | |
Jonathan Corbet | ef40203 | 2008-03-28 11:22:38 -0600 | [diff] [blame] | 538 | |
Jonathan Corbet | ccae861 | 2014-12-23 08:49:18 -0700 | [diff] [blame] | 539 | 13) Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes: |
Jonathan Corbet | d00c455 | 2014-12-23 08:54:36 -0700 | [diff] [blame] | 540 | -------------------------------------------------------------------------- |
Jonathan Corbet | bbb0a424 | 2009-01-16 09:49:50 -0700 | [diff] [blame] | 541 | |
Dan Carpenter | d75ef70 | 2014-10-29 13:01:36 +0300 | [diff] [blame] | 542 | The Reported-by tag gives credit to people who find bugs and report them and it |
| 543 | hopefully inspires them to help us again in the future. Please note that if |
| 544 | the bug was reported in private, then ask for permission first before using the |
| 545 | Reported-by tag. |
Jonathan Corbet | ef40203 | 2008-03-28 11:22:38 -0600 | [diff] [blame] | 546 | |
| 547 | A Tested-by: tag indicates that the patch has been successfully tested (in |
| 548 | some environment) by the person named. This tag informs maintainers that |
| 549 | some testing has been performed, provides a means to locate testers for |
| 550 | future patches, and ensures credit for the testers. |
| 551 | |
| 552 | Reviewed-by:, instead, indicates that the patch has been reviewed and found |
| 553 | acceptable according to the Reviewer's Statement: |
| 554 | |
| 555 | Reviewer's statement of oversight |
| 556 | |
| 557 | By offering my Reviewed-by: tag, I state that: |
| 558 | |
| 559 | (a) I have carried out a technical review of this patch to |
| 560 | evaluate its appropriateness and readiness for inclusion into |
| 561 | the mainline kernel. |
| 562 | |
| 563 | (b) Any problems, concerns, or questions relating to the patch |
| 564 | have been communicated back to the submitter. I am satisfied |
| 565 | with the submitter's response to my comments. |
| 566 | |
| 567 | (c) While there may be things that could be improved with this |
| 568 | submission, I believe that it is, at this time, (1) a |
| 569 | worthwhile modification to the kernel, and (2) free of known |
| 570 | issues which would argue against its inclusion. |
| 571 | |
| 572 | (d) While I have reviewed the patch and believe it to be sound, I |
| 573 | do not (unless explicitly stated elsewhere) make any |
| 574 | warranties or guarantees that it will achieve its stated |
| 575 | purpose or function properly in any given situation. |
| 576 | |
| 577 | A Reviewed-by tag is a statement of opinion that the patch is an |
| 578 | appropriate modification of the kernel without any remaining serious |
| 579 | technical issues. Any interested reviewer (who has done the work) can |
| 580 | offer a Reviewed-by tag for a patch. This tag serves to give credit to |
| 581 | reviewers and to inform maintainers of the degree of review which has been |
| 582 | done on the patch. Reviewed-by: tags, when supplied by reviewers known to |
| 583 | understand the subject area and to perform thorough reviews, will normally |
Pavel Machek | 5801da1 | 2009-06-04 16:26:50 +0200 | [diff] [blame] | 584 | increase the likelihood of your patch getting into the kernel. |
Jonathan Corbet | ef40203 | 2008-03-28 11:22:38 -0600 | [diff] [blame] | 585 | |
Mugunthan V N | 8543ae1 | 2013-04-29 16:18:17 -0700 | [diff] [blame] | 586 | A Suggested-by: tag indicates that the patch idea is suggested by the person |
| 587 | named and ensures credit to the person for the idea. Please note that this |
| 588 | tag should not be added without the reporter's permission, especially if the |
| 589 | idea was not posted in a public forum. That said, if we diligently credit our |
| 590 | idea reporters, they will, hopefully, be inspired to help us again in the |
| 591 | future. |
| 592 | |
Jacob Keller | 8401aa1 | 2014-06-06 14:36:39 -0700 | [diff] [blame] | 593 | A Fixes: tag indicates that the patch fixes an issue in a previous commit. It |
| 594 | is used to make it easy to determine where a bug originated, which can help |
| 595 | review a bug fix. This tag also assists the stable kernel team in determining |
| 596 | which stable kernel versions should receive your fix. This is the preferred |
| 597 | method for indicating a bug fixed by the patch. See #2 above for more details. |
| 598 | |
Jonathan Corbet | ef40203 | 2008-03-28 11:22:38 -0600 | [diff] [blame] | 599 | |
Jonathan Corbet | ccae861 | 2014-12-23 08:49:18 -0700 | [diff] [blame] | 600 | 14) The canonical patch format |
Jonathan Corbet | 7994cc1 | 2014-12-23 08:43:41 -0700 | [diff] [blame] | 601 | ------------------------------ |
| 602 | |
| 603 | This section describes how the patch itself should be formatted. Note |
| 604 | that, if you have your patches stored in a git repository, proper patch |
| 605 | formatting can be had with "git format-patch". The tools cannot create |
| 606 | the necessary text, though, so read the instructions below anyway. |
Randy Dunlap | 84da7c0 | 2005-06-28 20:45:30 -0700 | [diff] [blame] | 607 | |
Paul Jackson | 75f8426 | 2005-10-02 18:01:42 -0700 | [diff] [blame] | 608 | The canonical patch subject line is: |
| 609 | |
Paul Jackson | d6b9acc | 2005-10-03 00:29:10 -0700 | [diff] [blame] | 610 | Subject: [PATCH 001/123] subsystem: summary phrase |
Paul Jackson | 75f8426 | 2005-10-02 18:01:42 -0700 | [diff] [blame] | 611 | |
| 612 | The canonical patch message body contains the following: |
| 613 | |
Jonathan Corbet | ccae861 | 2014-12-23 08:49:18 -0700 | [diff] [blame] | 614 | - A "from" line specifying the patch author (only needed if the person |
| 615 | sending the patch is not the author). |
Paul Jackson | 75f8426 | 2005-10-02 18:01:42 -0700 | [diff] [blame] | 616 | |
| 617 | - An empty line. |
| 618 | |
Joe Perches | 2a076f4 | 2015-04-16 12:44:28 -0700 | [diff] [blame] | 619 | - The body of the explanation, line wrapped at 75 columns, which will |
| 620 | be copied to the permanent changelog to describe this patch. |
Paul Jackson | 75f8426 | 2005-10-02 18:01:42 -0700 | [diff] [blame] | 621 | |
| 622 | - The "Signed-off-by:" lines, described above, which will |
| 623 | also go in the changelog. |
| 624 | |
| 625 | - A marker line containing simply "---". |
| 626 | |
| 627 | - Any additional comments not suitable for the changelog. |
| 628 | |
| 629 | - The actual patch (diff output). |
| 630 | |
| 631 | The Subject line format makes it very easy to sort the emails |
| 632 | alphabetically by subject line - pretty much any email reader will |
| 633 | support that - since because the sequence number is zero-padded, |
| 634 | the numerical and alphabetic sort is the same. |
| 635 | |
Paul Jackson | d6b9acc | 2005-10-03 00:29:10 -0700 | [diff] [blame] | 636 | The "subsystem" in the email's Subject should identify which |
| 637 | area or subsystem of the kernel is being patched. |
| 638 | |
| 639 | The "summary phrase" in the email's Subject should concisely |
| 640 | describe the patch which that email contains. The "summary |
| 641 | phrase" should not be a filename. Do not use the same "summary |
Randy Dunlap | 66effdc | 2007-05-09 02:33:42 -0700 | [diff] [blame] | 642 | phrase" for every patch in a whole patch series (where a "patch |
| 643 | series" is an ordered sequence of multiple, related patches). |
Paul Jackson | d6b9acc | 2005-10-03 00:29:10 -0700 | [diff] [blame] | 644 | |
Theodore Ts'o | 2ae19ac | 2009-04-16 07:44:45 -0400 | [diff] [blame] | 645 | Bear in mind that the "summary phrase" of your email becomes a |
| 646 | globally-unique identifier for that patch. It propagates all the way |
| 647 | into the git changelog. The "summary phrase" may later be used in |
| 648 | developer discussions which refer to the patch. People will want to |
| 649 | google for the "summary phrase" to read discussion regarding that |
| 650 | patch. It will also be the only thing that people may quickly see |
| 651 | when, two or three months later, they are going through perhaps |
| 652 | thousands of patches using tools such as "gitk" or "git log |
| 653 | --oneline". |
| 654 | |
| 655 | For these reasons, the "summary" must be no more than 70-75 |
| 656 | characters, and it must describe both what the patch changes, as well |
| 657 | as why the patch might be necessary. It is challenging to be both |
| 658 | succinct and descriptive, but that is what a well-written summary |
| 659 | should do. |
| 660 | |
| 661 | The "summary phrase" may be prefixed by tags enclosed in square |
| 662 | brackets: "Subject: [PATCH tag] <summary phrase>". The tags are not |
| 663 | considered part of the summary phrase, but describe how the patch |
| 664 | should be treated. Common tags might include a version descriptor if |
| 665 | the multiple versions of the patch have been sent out in response to |
| 666 | comments (i.e., "v1, v2, v3"), or "RFC" to indicate a request for |
| 667 | comments. If there are four patches in a patch series the individual |
| 668 | patches may be numbered like this: 1/4, 2/4, 3/4, 4/4. This assures |
| 669 | that developers understand the order in which the patches should be |
| 670 | applied and that they have reviewed or applied all of the patches in |
| 671 | the patch series. |
Paul Jackson | d6b9acc | 2005-10-03 00:29:10 -0700 | [diff] [blame] | 672 | |
| 673 | A couple of example Subjects: |
| 674 | |
| 675 | Subject: [patch 2/5] ext2: improve scalability of bitmap searching |
| 676 | Subject: [PATCHv2 001/207] x86: fix eflags tracking |
Paul Jackson | 75f8426 | 2005-10-02 18:01:42 -0700 | [diff] [blame] | 677 | |
| 678 | The "from" line must be the very first line in the message body, |
| 679 | and has the form: |
| 680 | |
| 681 | From: Original Author <author@example.com> |
| 682 | |
| 683 | The "from" line specifies who will be credited as the author of the |
| 684 | patch in the permanent changelog. If the "from" line is missing, |
| 685 | then the "From:" line from the email header will be used to determine |
| 686 | the patch author in the changelog. |
| 687 | |
| 688 | The explanation body will be committed to the permanent source |
| 689 | changelog, so should make sense to a competent reader who has long |
| 690 | since forgotten the immediate details of the discussion that might |
Theodore Ts'o | 2ae19ac | 2009-04-16 07:44:45 -0400 | [diff] [blame] | 691 | have led to this patch. Including symptoms of the failure which the |
| 692 | patch addresses (kernel log messages, oops messages, etc.) is |
| 693 | especially useful for people who might be searching the commit logs |
| 694 | looking for the applicable patch. If a patch fixes a compile failure, |
| 695 | it may not be necessary to include _all_ of the compile failures; just |
| 696 | enough that it is likely that someone searching for the patch can find |
| 697 | it. As in the "summary phrase", it is important to be both succinct as |
| 698 | well as descriptive. |
Paul Jackson | 75f8426 | 2005-10-02 18:01:42 -0700 | [diff] [blame] | 699 | |
| 700 | The "---" marker line serves the essential purpose of marking for patch |
| 701 | handling tools where the changelog message ends. |
| 702 | |
| 703 | One good use for the additional comments after the "---" marker is for |
Theodore Ts'o | 2ae19ac | 2009-04-16 07:44:45 -0400 | [diff] [blame] | 704 | a diffstat, to show what files have changed, and the number of |
| 705 | inserted and deleted lines per file. A diffstat is especially useful |
| 706 | on bigger patches. Other comments relevant only to the moment or the |
| 707 | maintainer, not suitable for the permanent changelog, should also go |
| 708 | here. A good example of such comments might be "patch changelogs" |
| 709 | which describe what has changed between the v1 and v2 version of the |
| 710 | patch. |
| 711 | |
| 712 | If you are going to include a diffstat after the "---" marker, please |
| 713 | use diffstat options "-p 1 -w 70" so that filenames are listed from |
| 714 | the top of the kernel source tree and don't use too much horizontal |
Josh Triplett | 8e3072a | 2014-04-03 14:48:30 -0700 | [diff] [blame] | 715 | space (easily fit in 80 columns, maybe with some indentation). (git |
| 716 | generates appropriate diffstats by default.) |
Paul Jackson | 75f8426 | 2005-10-02 18:01:42 -0700 | [diff] [blame] | 717 | |
| 718 | See more details on the proper patch format in the following |
| 719 | references. |
| 720 | |
| 721 | |
Jonathan Corbet | ccae861 | 2014-12-23 08:49:18 -0700 | [diff] [blame] | 722 | 15) Sending "git pull" requests |
Jonathan Corbet | 7994cc1 | 2014-12-23 08:43:41 -0700 | [diff] [blame] | 723 | ------------------------------- |
Randy Dunlap | 84da7c0 | 2005-06-28 20:45:30 -0700 | [diff] [blame] | 724 | |
Jonathan Corbet | 7994cc1 | 2014-12-23 08:43:41 -0700 | [diff] [blame] | 725 | If you have a series of patches, it may be most convenient to have the |
| 726 | maintainer pull them directly into the subsystem repository with a |
| 727 | "git pull" operation. Note, however, that pulling patches from a developer |
| 728 | requires a higher degree of trust than taking patches from a mailing list. |
| 729 | As a result, many subsystem maintainers are reluctant to take pull |
Jonathan Corbet | b792ffe | 2014-12-23 09:28:40 -0700 | [diff] [blame] | 730 | requests, especially from new, unknown developers. If in doubt you can use |
| 731 | the pull request as the cover letter for a normal posting of the patch |
| 732 | series, giving the maintainer the option of using either. |
Randy Dunlap | 1486361 | 2008-07-27 20:44:24 -0700 | [diff] [blame] | 733 | |
Jonathan Corbet | 7994cc1 | 2014-12-23 08:43:41 -0700 | [diff] [blame] | 734 | A pull request should have [GIT] or [PULL] in the subject line. The |
| 735 | request itself should include the repository name and the branch of |
| 736 | interest on a single line; it should look something like: |
Randy Dunlap | 1486361 | 2008-07-27 20:44:24 -0700 | [diff] [blame] | 737 | |
Jonathan Corbet | 7994cc1 | 2014-12-23 08:43:41 -0700 | [diff] [blame] | 738 | Please pull from |
Randy Dunlap | 1486361 | 2008-07-27 20:44:24 -0700 | [diff] [blame] | 739 | |
Jonathan Corbet | 7994cc1 | 2014-12-23 08:43:41 -0700 | [diff] [blame] | 740 | git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus |
Randy Dunlap | 1486361 | 2008-07-27 20:44:24 -0700 | [diff] [blame] | 741 | |
Jonathan Corbet | 7994cc1 | 2014-12-23 08:43:41 -0700 | [diff] [blame] | 742 | to get these changes:" |
Randy Dunlap | 1486361 | 2008-07-27 20:44:24 -0700 | [diff] [blame] | 743 | |
Jonathan Corbet | 7994cc1 | 2014-12-23 08:43:41 -0700 | [diff] [blame] | 744 | A pull request should also include an overall message saying what will be |
| 745 | included in the request, a "git shortlog" listing of the patches |
| 746 | themselves, and a diffstat showing the overall effect of the patch series. |
| 747 | The easiest way to get all this information together is, of course, to let |
| 748 | git do it for you with the "git request-pull" command. |
Randy Dunlap | 1486361 | 2008-07-27 20:44:24 -0700 | [diff] [blame] | 749 | |
Jonathan Corbet | 7994cc1 | 2014-12-23 08:43:41 -0700 | [diff] [blame] | 750 | Some maintainers (including Linus) want to see pull requests from signed |
| 751 | commits; that increases their confidence that the request actually came |
| 752 | from you. Linus, in particular, will not pull from public hosting sites |
| 753 | like GitHub in the absence of a signed tag. |
Randy Dunlap | 1486361 | 2008-07-27 20:44:24 -0700 | [diff] [blame] | 754 | |
Jonathan Corbet | 7994cc1 | 2014-12-23 08:43:41 -0700 | [diff] [blame] | 755 | The first step toward creating such tags is to make a GNUPG key and get it |
| 756 | signed by one or more core kernel developers. This step can be hard for |
| 757 | new developers, but there is no way around it. Attending conferences can |
| 758 | be a good way to find developers who can sign your key. |
Randy Dunlap | 1486361 | 2008-07-27 20:44:24 -0700 | [diff] [blame] | 759 | |
Jonathan Corbet | 7994cc1 | 2014-12-23 08:43:41 -0700 | [diff] [blame] | 760 | Once you have prepared a patch series in git that you wish to have somebody |
| 761 | pull, create a signed tag with "git tag -s". This will create a new tag |
| 762 | identifying the last commit in the series and containing a signature |
| 763 | created with your private key. You will also have the opportunity to add a |
| 764 | changelog-style message to the tag; this is an ideal place to describe the |
| 765 | effects of the pull request as a whole. |
Randy Dunlap | 84da7c0 | 2005-06-28 20:45:30 -0700 | [diff] [blame] | 766 | |
Jonathan Corbet | 7994cc1 | 2014-12-23 08:43:41 -0700 | [diff] [blame] | 767 | If the tree the maintainer will be pulling from is not the repository you |
| 768 | are working from, don't forget to push the signed tag explicitly to the |
| 769 | public tree. |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 770 | |
Jonathan Corbet | 7994cc1 | 2014-12-23 08:43:41 -0700 | [diff] [blame] | 771 | When generating your pull request, use the signed tag as the target. A |
| 772 | command like this will do the trick: |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 773 | |
Jonathan Corbet | 7994cc1 | 2014-12-23 08:43:41 -0700 | [diff] [blame] | 774 | git request-pull master git://my.public.tree/linux.git my-signed-tag |
Xose Vazquez Perez | 5b0ed2c | 2006-01-08 01:02:49 -0800 | [diff] [blame] | 775 | |
| 776 | |
| 777 | ---------------------- |
Jonathan Corbet | 6de16eb | 2014-12-23 08:38:24 -0700 | [diff] [blame] | 778 | SECTION 2 - REFERENCES |
Xose Vazquez Perez | 5b0ed2c | 2006-01-08 01:02:49 -0800 | [diff] [blame] | 779 | ---------------------- |
| 780 | |
| 781 | Andrew Morton, "The perfect patch" (tpp). |
Mitchel Humpherys | 37c703f | 2014-04-03 14:50:40 -0700 | [diff] [blame] | 782 | <http://www.ozlabs.org/~akpm/stuff/tpp.txt> |
Xose Vazquez Perez | 5b0ed2c | 2006-01-08 01:02:49 -0800 | [diff] [blame] | 783 | |
Pavel Machek | 8e9cb8f | 2006-09-29 02:01:29 -0700 | [diff] [blame] | 784 | Jeff Garzik, "Linux kernel patch submission format". |
Xose Vazquez Perez | 5b0ed2c | 2006-01-08 01:02:49 -0800 | [diff] [blame] | 785 | <http://linux.yyz.us/patch-format.html> |
| 786 | |
Pavel Machek | 8e9cb8f | 2006-09-29 02:01:29 -0700 | [diff] [blame] | 787 | Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". |
Vikram Narayanan | f503993 | 2011-05-23 12:01:25 -0700 | [diff] [blame] | 788 | <http://www.kroah.com/log/linux/maintainer.html> |
| 789 | <http://www.kroah.com/log/linux/maintainer-02.html> |
| 790 | <http://www.kroah.com/log/linux/maintainer-03.html> |
| 791 | <http://www.kroah.com/log/linux/maintainer-04.html> |
| 792 | <http://www.kroah.com/log/linux/maintainer-05.html> |
Sudip Mukherjee | 7e0dae6 | 2014-09-07 11:26:12 -0700 | [diff] [blame] | 793 | <http://www.kroah.com/log/linux/maintainer-06.html> |
Xose Vazquez Perez | 5b0ed2c | 2006-01-08 01:02:49 -0800 | [diff] [blame] | 794 | |
Randy Dunlap | bc7455f | 2006-07-30 03:03:45 -0700 | [diff] [blame] | 795 | NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! |
Mitchel Humpherys | 37c703f | 2014-04-03 14:50:40 -0700 | [diff] [blame] | 796 | <https://lkml.org/lkml/2005/7/11/336> |
Xose Vazquez Perez | 5b0ed2c | 2006-01-08 01:02:49 -0800 | [diff] [blame] | 797 | |
Pavel Machek | 8e9cb8f | 2006-09-29 02:01:29 -0700 | [diff] [blame] | 798 | Kernel Documentation/CodingStyle: |
Luis de Bethencourt | 60498bb | 2015-07-03 16:22:11 +0100 | [diff] [blame] | 799 | <Documentation/CodingStyle> |
Xose Vazquez Perez | 5b0ed2c | 2006-01-08 01:02:49 -0800 | [diff] [blame] | 800 | |
Pavel Machek | 8e9cb8f | 2006-09-29 02:01:29 -0700 | [diff] [blame] | 801 | Linus Torvalds's mail on the canonical patch format: |
Xose Vazquez Perez | 5b0ed2c | 2006-01-08 01:02:49 -0800 | [diff] [blame] | 802 | <http://lkml.org/lkml/2005/4/7/183> |
Andi Kleen | 9536727 | 2008-10-15 22:02:02 -0700 | [diff] [blame] | 803 | |
| 804 | Andi Kleen, "On submitting kernel patches" |
Lucas De Marchi | 25985ed | 2011-03-30 22:57:33 -0300 | [diff] [blame] | 805 | Some strategies to get difficult or controversial changes in. |
Andi Kleen | 9536727 | 2008-10-15 22:02:02 -0700 | [diff] [blame] | 806 | http://halobates.de/on-submitting-patches.pdf |
| 807 | |
Xose Vazquez Perez | 5b0ed2c | 2006-01-08 01:02:49 -0800 | [diff] [blame] | 808 | -- |