aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorJonathan Corbet <corbet@lwn.net>2015-01-29 15:08:28 -0500
committerJonathan Corbet <corbet@lwn.net>2015-01-29 15:11:58 -0500
commitfbd3a466123bf449b25c26e23d4d79cf722a76cc (patch)
tree4f9a46fad5a70a1aa9bb1ab5a400f609d55cd5e8
parent5e857b667cc4b2778a1b4edb95177381d0b36243 (diff)
parentb792ffe464f64c84c48d51e01c0fecabc4b39579 (diff)
Merge branch 'doc/sp-update' into docs-next
Bring in the big SubmittingPatches thrashup. Conflicts: Documentation/SubmittingPatches
-rw-r--r--Documentation/SubmittingPatches436
1 files changed, 216 insertions, 220 deletions
diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 1671ce323a02..447671bd2927 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -10,27 +10,49 @@ kernel, the process can sometimes be daunting if you're not familiar
10with "the system." This text is a collection of suggestions which 10with "the system." This text is a collection of suggestions which
11can greatly increase the chances of your change being accepted. 11can greatly increase the chances of your change being accepted.
12 12
13Read Documentation/SubmitChecklist for a list of items to check 13This document contains a large number of suggestions in a relatively terse
14before submitting code. If you are submitting a driver, also read 14format. For detailed information on how the kernel development process
15Documentation/SubmittingDrivers. 15works, see Documentation/development-process. Also, read
16Documentation/SubmitChecklist for a list of items to check before
17submitting code. If you are submitting a driver, also read
18Documentation/SubmittingDrivers; for device tree binding patches, read
19Documentation/devicetree/bindings/submitting-patches.txt.
16 20
17Many of these steps describe the default behavior of the git version 21Many of these steps describe the default behavior of the git version
18control system; if you use git to prepare your patches, you'll find much 22control system; if you use git to prepare your patches, you'll find much
19of the mechanical work done for you, though you'll still need to prepare 23of the mechanical work done for you, though you'll still need to prepare
20and document a sensible set of patches. 24and document a sensible set of patches. In general, use of git will make
25your life as a kernel developer easier.
21 26
22-------------------------------------------- 27--------------------------------------------
23SECTION 1 - CREATING AND SENDING YOUR CHANGE 28SECTION 1 - CREATING AND SENDING YOUR CHANGE
24-------------------------------------------- 29--------------------------------------------
25 30
26 31
320) Obtain a current source tree
33-------------------------------
34
35If you do not have a repository with the current kernel source handy, use
36git to obtain one. You'll want to start with the mainline repository,
37which can be grabbed with:
38
39 git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
40
41Note, however, that you may not want to develop against the mainline tree
42directly. Most subsystem maintainers run their own trees and want to see
43patches prepared against those trees. See the "T:" entry for the subsystem
44in the MAINTAINERS file to find that tree, or simply ask the maintainer if
45the tree is not listed there.
46
47It is still possible to download kernel releases via tarballs (as described
48in the next section), but that is the hard way to do kernel development.
27 49
281) "diff -up" 501) "diff -up"
29------------ 51------------
30 52
31Use "diff -up" or "diff -uprN" to create patches. git generates patches 53If you must generate your patches by hand, use "diff -up" or "diff -uprN"
32in this form by default; if you're using git, you can skip this section 54to create patches. Git generates patches in this form by default; if
33entirely. 55you're using git, you can skip this section entirely.
34 56
35All changes to the Linux kernel occur in the form of patches, as 57All changes to the Linux kernel occur in the form of patches, as
36generated by diff(1). When creating your patch, make sure to create it 58generated by diff(1). When creating your patch, make sure to create it
@@ -42,7 +64,7 @@ not in any lower subdirectory.
42 64
43To create a patch for a single file, it is often sufficient to do: 65To create a patch for a single file, it is often sufficient to do:
44 66
45 SRCTREE= linux-2.6 67 SRCTREE= linux
46 MYFILE= drivers/net/mydriver.c 68 MYFILE= drivers/net/mydriver.c
47 69
48 cd $SRCTREE 70 cd $SRCTREE
@@ -55,17 +77,16 @@ To create a patch for multiple files, you should unpack a "vanilla",
55or unmodified kernel source tree, and generate a diff against your 77or unmodified kernel source tree, and generate a diff against your
56own source tree. For example: 78own source tree. For example:
57 79
58 MYSRC= /devel/linux-2.6 80 MYSRC= /devel/linux
59 81
60 tar xvfz linux-2.6.12.tar.gz 82 tar xvfz linux-3.19.tar.gz
61 mv linux-2.6.12 linux-2.6.12-vanilla 83 mv linux-3.19 linux-3.19-vanilla
62 diff -uprN -X linux-2.6.12-vanilla/Documentation/dontdiff \ 84 diff -uprN -X linux-3.19-vanilla/Documentation/dontdiff \
63 linux-2.6.12-vanilla $MYSRC > /tmp/patch 85 linux-3.19-vanilla $MYSRC > /tmp/patch
64 86
65"dontdiff" is a list of files which are generated by the kernel during 87"dontdiff" is a list of files which are generated by the kernel during
66the build process, and should be ignored in any diff(1)-generated 88the build process, and should be ignored in any diff(1)-generated
67patch. The "dontdiff" file is included in the kernel tree in 89patch.
682.6.12 and later.
69 90
70Make sure your patch does not include any extra files which do not 91Make sure your patch does not include any extra files which do not
71belong in a patch submission. Make sure to review your patch -after- 92belong in a patch submission. Make sure to review your patch -after-
@@ -83,6 +104,7 @@ is another popular alternative.
83 104
84 105
852) Describe your changes. 1062) Describe your changes.
107-------------------------
86 108
87Describe your problem. Whether your patch is a one-line bug fix or 109Describe your problem. Whether your patch is a one-line bug fix or
885000 lines of a new feature, there must be an underlying problem that 1105000 lines of a new feature, there must be an underlying problem that
@@ -124,10 +146,10 @@ See #3, next.
124When you submit or resubmit a patch or patch series, include the 146When you submit or resubmit a patch or patch series, include the
125complete patch description and justification for it. Don't just 147complete patch description and justification for it. Don't just
126say that this is version N of the patch (series). Don't expect the 148say that this is version N of the patch (series). Don't expect the
127patch merger to refer back to earlier patch versions or referenced 149subsystem maintainer to refer back to earlier patch versions or referenced
128URLs to find the patch description and put that into the patch. 150URLs to find the patch description and put that into the patch.
129I.e., the patch (series) and its description should be self-contained. 151I.e., the patch (series) and its description should be self-contained.
130This benefits both the patch merger(s) and reviewers. Some reviewers 152This benefits both the maintainers and reviewers. Some reviewers
131probably didn't even receive earlier versions of the patch. 153probably didn't even receive earlier versions of the patch.
132 154
133Describe your changes in imperative mood, e.g. "make xyzzy do frotz" 155Describe your changes in imperative mood, e.g. "make xyzzy do frotz"
@@ -156,10 +178,15 @@ Example:
156 platform_set_drvdata(), but left the variable "dev" unused, 178 platform_set_drvdata(), but left the variable "dev" unused,
157 delete it. 179 delete it.
158 180
181You should also be sure to use at least the first twelve characters of the
182SHA-1 ID. The kernel repository holds a *lot* of objects, making
183collisions with shorter IDs a real possibility. Bear in mind that, even if
184there is no collision with your six-character ID now, that condition may
185change five years from now.
186
159If your patch fixes a bug in a specific commit, e.g. you found an issue using 187If your patch fixes a bug in a specific commit, e.g. you found an issue using
160git-bisect, please use the 'Fixes:' tag with the first 12 characters of the 188git-bisect, please use the 'Fixes:' tag with the first 12 characters of the
161SHA-1 ID, and the one line summary. 189SHA-1 ID, and the one line summary. For example:
162Example:
163 190
164 Fixes: e21d2170f366 ("video: remove unnecessary platform_set_drvdata()") 191 Fixes: e21d2170f366 ("video: remove unnecessary platform_set_drvdata()")
165 192
@@ -172,8 +199,9 @@ outputting the above style in the git log or git show commands
172 fixes = Fixes: %h (\"%s\") 199 fixes = Fixes: %h (\"%s\")
173 200
1743) Separate your changes. 2013) Separate your changes.
202-------------------------
175 203
176Separate _logical changes_ into a single patch file. 204Separate each _logical change_ into a separate patch.
177 205
178For example, if your changes include both bug fixes and performance 206For example, if your changes include both bug fixes and performance
179enhancements for a single driver, separate those changes into two 207enhancements for a single driver, separate those changes into two
@@ -184,90 +212,116 @@ On the other hand, if you make a single change to numerous files,
184group those changes into a single patch. Thus a single logical change 212group those changes into a single patch. Thus a single logical change
185is contained within a single patch. 213is contained within a single patch.
186 214
215The point to remember is that each patch should make an easily understood
216change that can be verified by reviewers. Each patch should be justifiable
217on its own merits.
218
187If one patch depends on another patch in order for a change to be 219If one patch depends on another patch in order for a change to be
188complete, that is OK. Simply note "this patch depends on patch X" 220complete, that is OK. Simply note "this patch depends on patch X"
189in your patch description. 221in your patch description.
190 222
223When dividing your change into a series of patches, take special care to
224ensure that the kernel builds and runs properly after each patch in the
225series. Developers using "git bisect" to track down a problem can end up
226splitting your patch series at any point; they will not thank you if you
227introduce bugs in the middle.
228
191If you cannot condense your patch set into a smaller set of patches, 229If you cannot condense your patch set into a smaller set of patches,
192then only post say 15 or so at a time and wait for review and integration. 230then only post say 15 or so at a time and wait for review and integration.
193 231
194 232
195 233
1964) Style check your changes. 2344) Style-check your changes.
235----------------------------
197 236
198Check your patch for basic style violations, details of which can be 237Check your patch for basic style violations, details of which can be
199found in Documentation/CodingStyle. Failure to do so simply wastes 238found in Documentation/CodingStyle. Failure to do so simply wastes
200the reviewers time and will get your patch rejected, probably 239the reviewers time and will get your patch rejected, probably
201without even being read. 240without even being read.
202 241
203At a minimum you should check your patches with the patch style 242One significant exception is when moving code from one file to
204checker prior to submission (scripts/checkpatch.pl). You should 243another -- in this case you should not modify the moved code at all in
205be able to justify all violations that remain in your patch. 244the same patch which moves it. This clearly delineates the act of
245moving the code and your changes. This greatly aids review of the
246actual differences and allows tools to better track the history of
247the code itself.
248
249Check your patches with the patch style checker prior to submission
250(scripts/checkpatch.pl). Note, though, that the style checker should be
251viewed as a guide, not as a replacement for human judgment. If your code
252looks better with a violation then its probably best left alone.
253
254The 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
206 258
259You should be able to justify all violations that remain in your
260patch.
207 261
208 262
2095) Select e-mail destination. 2635) Select the recipients for your patch.
264----------------------------------------
210 265
211Look through the MAINTAINERS file and the source code, and determine 266You should always copy the appropriate subsystem maintainer(s) on any patch
212if your change applies to a specific subsystem of the kernel, with 267to code that they maintain; look through the MAINTAINERS file and the
213an assigned maintainer. If so, e-mail that person. The script 268source code revision history to see who those maintainers are. The
214scripts/get_maintainer.pl can be very useful at this step. 269script scripts/get_maintainer.pl can be very useful at this step. If you
270cannot find a maintainer for the subsystem your are working on, Andrew
271Morton (akpm@linux-foundation.org) serves as a maintainer of last resort.
215 272
216If no maintainer is listed, or the maintainer does not respond, send 273You should also normally choose at least one mailing list to receive a copy
217your patch to the primary Linux kernel developer's mailing list, 274of your patch set. linux-kernel@vger.kernel.org functions as a list of
218linux-kernel@vger.kernel.org. Most kernel developers monitor this 275last resort, but the volume on that list has caused a number of developers
219e-mail list, and can comment on your changes. 276to tune it out. Look in the MAINTAINERS file for a subsystem-specific
277list; your patch will probably get more attention there. Please do not
278spam unrelated lists, though.
220 279
280Many kernel-related lists are hosted on vger.kernel.org; you can find a
281list of them at http://vger.kernel.org/vger-lists.html. There are
282kernel-related lists hosted elsewhere as well, though.
221 283
222Do not send more than 15 patches at once to the vger mailing lists!!! 284Do not send more than 15 patches at once to the vger mailing lists!!!
223 285
224
225Linus Torvalds is the final arbiter of all changes accepted into the 286Linus Torvalds is the final arbiter of all changes accepted into the
226Linux kernel. His e-mail address is <torvalds@linux-foundation.org>. 287Linux kernel. His e-mail address is <torvalds@linux-foundation.org>.
227He gets a lot of e-mail, so typically you should do your best to -avoid- 288He gets a lot of e-mail, and, at this point, very few patches go through
289Linus directly, so typically you should do your best to -avoid-
228sending him e-mail. 290sending him e-mail.
229 291
230Patches which are bug fixes, are "obvious" changes, or similarly 292If you have a patch that fixes an exploitable security bug, send that patch
231require little discussion should be sent or CC'd to Linus. Patches 293to security@kernel.org. For severe bugs, a short embargo may be considered
232which require discussion or do not have a clear advantage should 294to allow distrbutors to get the patch out to users; in such cases,
233usually be sent first to linux-kernel. Only after the patch is 295obviously, the patch should not be sent to any public lists.
234discussed should the patch then be submitted to Linus.
235
236
237 296
2386) Select your CC (e-mail carbon copy) list. 297Patches that fix a severe bug in a released kernel should be directed
298toward the stable maintainers by putting a line like this:
239 299
240Unless you have a reason NOT to do so, CC linux-kernel@vger.kernel.org. 300 Cc: stable@vger.kernel.org
241 301
242Other kernel developers besides Linus need to be aware of your change, 302into your patch.
243so that they may comment on it and offer code review and suggestions.
244linux-kernel is the primary Linux kernel developer mailing list.
245Other mailing lists are available for specific subsystems, such as
246USB, framebuffer devices, the VFS, the SCSI subsystem, etc. See the
247MAINTAINERS file for a mailing list that relates specifically to
248your change.
249 303
250Majordomo lists of VGER.KERNEL.ORG at: 304Note, however, that some subsystem maintainers want to come to their own
251 <http://vger.kernel.org/vger-lists.html> 305conclusions on which patches should go to the stable trees. The networking
306maintainer, in particular, would rather not see individual developers
307adding lines like the above to their patches.
252 308
253If changes affect userland-kernel interfaces, please send 309If changes affect userland-kernel interfaces, please send the MAN-PAGES
254the MAN-PAGES maintainer (as listed in the MAINTAINERS file) 310maintainer (as listed in the MAINTAINERS file) a man-pages patch, or at
255a man-pages patch, or at least a notification of the change, 311least a notification of the change, so that some information makes its way
256so that some information makes its way into the manual pages. 312into the manual pages. User-space API changes should also be copied to
257 313linux-api@vger.kernel.org.
258Even if the maintainer did not respond in step #5, make sure to ALWAYS
259copy the maintainer when you change their code.
260 314
261For small patches you may want to CC the Trivial Patch Monkey 315For small patches you may want to CC the Trivial Patch Monkey
262trivial@kernel.org which collects "trivial" patches. Have a look 316trivial@kernel.org which collects "trivial" patches. Have a look
263into the MAINTAINERS file for its current manager. 317into the MAINTAINERS file for its current manager.
264Trivial patches must qualify for one of the following rules: 318Trivial patches must qualify for one of the following rules:
265 Spelling fixes in documentation 319 Spelling fixes in documentation
266 Spelling fixes which could break grep(1) 320 Spelling fixes for errors which could break grep(1)
267 Warning fixes (cluttering with useless warnings is bad) 321 Warning fixes (cluttering with useless warnings is bad)
268 Compilation fixes (only if they are actually correct) 322 Compilation fixes (only if they are actually correct)
269 Runtime fixes (only if they actually fix things) 323 Runtime fixes (only if they actually fix things)
270 Removing use of deprecated functions/macros (eg. check_region) 324 Removing use of deprecated functions/macros
271 Contact detail and documentation fixes 325 Contact detail and documentation fixes
272 Non-portable code replaced by portable code (even in arch-specific, 326 Non-portable code replaced by portable code (even in arch-specific,
273 since people copy, as long as it's trivial) 327 since people copy, as long as it's trivial)
@@ -276,7 +330,8 @@ Trivial patches must qualify for one of the following rules:
276 330
277 331
278 332
2797) No MIME, no links, no compression, no attachments. Just plain text. 3336) No MIME, no links, no compression, no attachments. Just plain text.
334-----------------------------------------------------------------------
280 335
281Linus and other kernel developers need to be able to read and comment 336Linus and other kernel developers need to be able to read and comment
282on the changes you are submitting. It is important for a kernel 337on the changes you are submitting. It is important for a kernel
@@ -299,54 +354,48 @@ you to re-send them using MIME.
299See Documentation/email-clients.txt for hints about configuring 354See Documentation/email-clients.txt for hints about configuring
300your e-mail client so that it sends your patches untouched. 355your e-mail client so that it sends your patches untouched.
301 356
3028) E-mail size. 3577) E-mail size.
303 358---------------
304When sending patches to Linus, always follow step #7.
305 359
306Large changes are not appropriate for mailing lists, and some 360Large changes are not appropriate for mailing lists, and some
307maintainers. If your patch, uncompressed, exceeds 300 kB in size, 361maintainers. If your patch, uncompressed, exceeds 300 kB in size,
308it is preferred that you store your patch on an Internet-accessible 362it is preferred that you store your patch on an Internet-accessible
309server, and provide instead a URL (link) pointing to your patch. 363server, and provide instead a URL (link) pointing to your patch. But note
364that if your patch exceeds 300 kB, it almost certainly needs to be broken up
365anyway.
310 366
3678) Respond to review comments.
368------------------------------
311 369
370Your patch will almost certainly get comments from reviewers on ways in
371which the patch can be improved. You must respond to those comments;
372ignoring reviewers is a good way to get ignored in return. Review comments
373or questions that do not lead to a code change should almost certainly
374bring about a comment or changelog entry so that the next reviewer better
375understands what is going on.
312 376
3139) Name your kernel version. 377Be sure to tell the reviewers what changes you are making and to thank them
378for their time. Code review is a tiring and time-consuming process, and
379reviewers sometimes get grumpy. Even in that case, though, respond
380politely and address the problems they have pointed out.
314 381
315It is important to note, either in the subject line or in the patch
316description, the kernel version to which this patch applies.
317 382
318If the patch does not apply cleanly to the latest kernel version, 3839) Don't get discouraged - or impatient.
319Linus will not apply it. 384----------------------------------------
320 385
386After you have submitted your change, be patient and wait. Reviewers are
387busy people and may not get to your patch right away.
321 388
389Once upon a time, patches used to disappear into the void without comment,
390but the development process works more smoothly than that now. You should
391receive comments within a week or so; if that does not happen, make sure
392that you have sent your patches to the right place. Wait for a minimum of
393one week before resubmitting or pinging reviewers - possibly longer during
394busy times like merge windows.
322 395
32310) Don't get discouraged. Re-submit.
324 396
325After you have submitted your change, be patient and wait. If Linus 39710) Include PATCH in the subject
326likes your change and applies it, it will appear in the next version 398--------------------------------
327of the kernel that he releases.
328
329However, if your change doesn't appear in the next version of the
330kernel, there could be any number of reasons. It's YOUR job to
331narrow down those reasons, correct what was wrong, and submit your
332updated change.
333
334It is quite common for Linus to "drop" your patch without comment.
335That's the nature of the system. If he drops your patch, it could be
336due to
337* Your patch did not apply cleanly to the latest kernel version.
338* Your patch was not sufficiently discussed on linux-kernel.
339* A style issue (see section 2).
340* An e-mail formatting issue (re-read this section).
341* A technical problem with your change.
342* He gets tons of e-mail, and yours got lost in the shuffle.
343* You are being annoying.
344
345When in doubt, solicit comments on linux-kernel mailing list.
346
347
348
34911) Include PATCH in the subject
350 399
351Due to high e-mail traffic to Linus, and to linux-kernel, it is common 400Due to high e-mail traffic to Linus, and to linux-kernel, it is common
352convention to prefix your subject line with [PATCH]. This lets Linus 401convention to prefix your subject line with [PATCH]. This lets Linus
@@ -355,7 +404,8 @@ e-mail discussions.
355 404
356 405
357 406
35812) Sign your work 40711) Sign your work
408------------------
359 409
360To improve tracking of who did what, especially with patches that can 410To improve tracking of who did what, especially with patches that can
361percolate to their final resting place in the kernel through several 411percolate to their final resting place in the kernel through several
@@ -429,15 +479,15 @@ which appears in the changelog.
429Special note to back-porters: It seems to be a common and useful practice 479Special note to back-porters: It seems to be a common and useful practice
430to insert an indication of the origin of a patch at the top of the commit 480to insert an indication of the origin of a patch at the top of the commit
431message (just after the subject line) to facilitate tracking. For instance, 481message (just after the subject line) to facilitate tracking. For instance,
432here's what we see in 2.6-stable : 482here's what we see in a 3.x-stable release:
433 483
434 Date: Tue May 13 19:10:30 2008 +0000 484Date: Tue Oct 7 07:26:38 2014 -0400
435 485
436 SCSI: libiscsi regression in 2.6.25: fix nop timer handling 486 libata: Un-break ATA blacklist
437 487
438 commit 4cf1043593db6a337f10e006c23c69e5fc93e722 upstream 488 commit 1c40279960bcd7d52dbdf1d466b20d24b99176c8 upstream.
439 489
440And here's what appears in 2.4 : 490And here's what might appear in an older kernel once a patch is backported:
441 491
442 Date: Tue May 13 22:12:27 2008 +0200 492 Date: Tue May 13 22:12:27 2008 +0200
443 493
@@ -446,18 +496,19 @@ And here's what appears in 2.4 :
446 [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a] 496 [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a]
447 497
448Whatever the format, this information provides a valuable help to people 498Whatever the format, this information provides a valuable help to people
449tracking your trees, and to people trying to trouble-shoot bugs in your 499tracking your trees, and to people trying to troubleshoot bugs in your
450tree. 500tree.
451 501
452 502
45313) When to use Acked-by: and Cc: 50312) When to use Acked-by: and Cc:
504---------------------------------
454 505
455The Signed-off-by: tag indicates that the signer was involved in the 506The Signed-off-by: tag indicates that the signer was involved in the
456development of the patch, or that he/she was in the patch's delivery path. 507development of the patch, or that he/she was in the patch's delivery path.
457 508
458If a person was not directly involved in the preparation or handling of a 509If a person was not directly involved in the preparation or handling of a
459patch but wishes to signify and record their approval of it then they can 510patch but wishes to signify and record their approval of it then they can
460arrange to have an Acked-by: line added to the patch's changelog. 511ask to have an Acked-by: line added to the patch's changelog.
461 512
462Acked-by: is often used by the maintainer of the affected code when that 513Acked-by: is often used by the maintainer of the affected code when that
463maintainer neither contributed to nor forwarded the patch. 514maintainer neither contributed to nor forwarded the patch.
@@ -465,7 +516,8 @@ maintainer neither contributed to nor forwarded the patch.
465Acked-by: is not as formal as Signed-off-by:. It is a record that the acker 516Acked-by: is not as formal as Signed-off-by:. It is a record that the acker
466has at least reviewed the patch and has indicated acceptance. Hence patch 517has at least reviewed the patch and has indicated acceptance. Hence patch
467mergers will sometimes manually convert an acker's "yep, looks good to me" 518mergers will sometimes manually convert an acker's "yep, looks good to me"
468into an Acked-by:. 519into an Acked-by: (but note that it is usually better to ask for an
520explicit ack).
469 521
470Acked-by: does not necessarily indicate acknowledgement of the entire patch. 522Acked-by: does not necessarily indicate acknowledgement of the entire patch.
471For example, if a patch affects multiple subsystems and has an Acked-by: from 523For example, if a patch affects multiple subsystems and has an Acked-by: from
@@ -477,11 +529,13 @@ list archives.
477If a person has had the opportunity to comment on a patch, but has not 529If a person has had the opportunity to comment on a patch, but has not
478provided such comments, you may optionally add a "Cc:" tag to the patch. 530provided such comments, you may optionally add a "Cc:" tag to the patch.
479This is the only tag which might be added without an explicit action by the 531This is the only tag which might be added without an explicit action by the
480person it names. This tag documents that potentially interested parties 532person it names - but it should indicate that this person was copied on the
481have been included in the discussion 533patch. This tag documents that potentially interested parties
534have been included in the discussion.
482 535
483 536
48414) Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes: 53713) Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes:
538--------------------------------------------------------------------------
485 539
486The Reported-by tag gives credit to people who find bugs and report them and it 540The Reported-by tag gives credit to people who find bugs and report them and it
487hopefully inspires them to help us again in the future. Please note that if 541hopefully inspires them to help us again in the future. Please note that if
@@ -541,7 +595,13 @@ which stable kernel versions should receive your fix. This is the preferred
541method for indicating a bug fixed by the patch. See #2 above for more details. 595method for indicating a bug fixed by the patch. See #2 above for more details.
542 596
543 597
54415) The canonical patch format 59814) The canonical patch format
599------------------------------
600
601This section describes how the patch itself should be formatted. Note
602that, if you have your patches stored in a git repository, proper patch
603formatting can be had with "git format-patch". The tools cannot create
604the necessary text, though, so read the instructions below anyway.
545 605
546The canonical patch subject line is: 606The canonical patch subject line is:
547 607
@@ -549,7 +609,8 @@ The canonical patch subject line is:
549 609
550The canonical patch message body contains the following: 610The canonical patch message body contains the following:
551 611
552 - A "from" line specifying the patch author. 612 - A "from" line specifying the patch author (only needed if the person
613 sending the patch is not the author).
553 614
554 - An empty line. 615 - An empty line.
555 616
@@ -656,128 +717,63 @@ See more details on the proper patch format in the following
656references. 717references.
657 718
658 719
65916) Sending "git pull" requests (from Linus emails) 72015) Sending "git pull" requests
660 721-------------------------------
661Please write the git repo address and branch name alone on the same line
662so that I can't even by mistake pull from the wrong branch, and so
663that a triple-click just selects the whole thing.
664
665So the proper format is something along the lines of:
666
667 "Please pull from
668
669 git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus
670
671 to get these changes:"
672
673so that I don't have to hunt-and-peck for the address and inevitably
674get it wrong (actually, I've only gotten it wrong a few times, and
675checking against the diffstat tells me when I get it wrong, but I'm
676just a lot more comfortable when I don't have to "look for" the right
677thing to pull, and double-check that I have the right branch-name).
678
679
680Please use "git diff -M --stat --summary" to generate the diffstat:
681the -M enables rename detection, and the summary enables a summary of
682new/deleted or renamed files.
683
684With rename detection, the statistics are rather different [...]
685because git will notice that a fair number of the changes are renames.
686
687-----------------------------------
688SECTION 2 - HINTS, TIPS, AND TRICKS
689-----------------------------------
690
691This section lists many of the common "rules" associated with code
692submitted to the kernel. There are always exceptions... but you must
693have a really good reason for doing so. You could probably call this
694section Linus Computer Science 101.
695
696
697
6981) Read Documentation/CodingStyle
699
700Nuff said. If your code deviates too much from this, it is likely
701to be rejected without further review, and without comment.
702
703One significant exception is when moving code from one file to
704another -- in this case you should not modify the moved code at all in
705the same patch which moves it. This clearly delineates the act of
706moving the code and your changes. This greatly aids review of the
707actual differences and allows tools to better track the history of
708the code itself.
709
710Check your patches with the patch style checker prior to submission
711(scripts/checkpatch.pl). The style checker should be viewed as
712a guide not as the final word. If your code looks better with
713a violation then its probably best left alone.
714
715The checker reports at three levels:
716 - ERROR: things that are very likely to be wrong
717 - WARNING: things requiring careful review
718 - CHECK: things requiring thought
719
720You should be able to justify all violations that remain in your
721patch.
722
723
724
7252) #ifdefs are ugly
726
727Code cluttered with ifdefs is difficult to read and maintain. Don't do
728it. Instead, put your ifdefs in a header, and conditionally define
729'static inline' functions, or macros, which are used in the code.
730Let the compiler optimize away the "no-op" case.
731
732Simple example, of poor code:
733
734 dev = alloc_etherdev (sizeof(struct funky_private));
735 if (!dev)
736 return -ENODEV;
737 #ifdef CONFIG_NET_FUNKINESS
738 init_funky_net(dev);
739 #endif
740
741Cleaned-up example:
742
743(in header)
744 #ifndef CONFIG_NET_FUNKINESS
745 static inline void init_funky_net (struct net_device *d) {}
746 #endif
747 722
748(in the code itself) 723If you have a series of patches, it may be most convenient to have the
749 dev = alloc_etherdev (sizeof(struct funky_private)); 724maintainer pull them directly into the subsystem repository with a
750 if (!dev) 725"git pull" operation. Note, however, that pulling patches from a developer
751 return -ENODEV; 726requires a higher degree of trust than taking patches from a mailing list.
752 init_funky_net(dev); 727As a result, many subsystem maintainers are reluctant to take pull
728requests, especially from new, unknown developers. If in doubt you can use
729the pull request as the cover letter for a normal posting of the patch
730series, giving the maintainer the option of using either.
753 731
732A pull request should have [GIT] or [PULL] in the subject line. The
733request itself should include the repository name and the branch of
734interest on a single line; it should look something like:
754 735
736 Please pull from
755 737
7563) 'static inline' is better than a macro 738 git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus
757 739
758Static inline functions are greatly preferred over macros. 740 to get these changes:"
759They provide type safety, have no length limitations, no formatting
760limitations, and under gcc they are as cheap as macros.
761 741
762Macros should only be used for cases where a static inline is clearly 742A pull request should also include an overall message saying what will be
763suboptimal [there are a few, isolated cases of this in fast paths], 743included in the request, a "git shortlog" listing of the patches
764or where it is impossible to use a static inline function [such as 744themselves, and a diffstat showing the overall effect of the patch series.
765string-izing]. 745The easiest way to get all this information together is, of course, to let
746git do it for you with the "git request-pull" command.
766 747
767'static inline' is preferred over 'static __inline__', 'extern inline', 748Some maintainers (including Linus) want to see pull requests from signed
768and 'extern __inline__'. 749commits; that increases their confidence that the request actually came
750from you. Linus, in particular, will not pull from public hosting sites
751like GitHub in the absence of a signed tag.
769 752
753The first step toward creating such tags is to make a GNUPG key and get it
754signed by one or more core kernel developers. This step can be hard for
755new developers, but there is no way around it. Attending conferences can
756be a good way to find developers who can sign your key.
770 757
758Once you have prepared a patch series in git that you wish to have somebody
759pull, create a signed tag with "git tag -s". This will create a new tag
760identifying the last commit in the series and containing a signature
761created with your private key. You will also have the opportunity to add a
762changelog-style message to the tag; this is an ideal place to describe the
763effects of the pull request as a whole.
771 764
7724) Don't over-design. 765If the tree the maintainer will be pulling from is not the repository you
766are working from, don't forget to push the signed tag explicitly to the
767public tree.
773 768
774Don't try to anticipate nebulous future cases which may or may not 769When generating your pull request, use the signed tag as the target. A
775be useful: "Make it as simple as you can, and no simpler." 770command like this will do the trick:
776 771
772 git request-pull master git://my.public.tree/linux.git my-signed-tag
777 773
778 774
779---------------------- 775----------------------
780SECTION 3 - REFERENCES 776SECTION 2 - REFERENCES
781---------------------- 777----------------------
782 778
783Andrew Morton, "The perfect patch" (tpp). 779Andrew Morton, "The perfect patch" (tpp).