Root/
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 | |
13 | Read Documentation/SubmitChecklist for a list of items to check |
14 | before submitting code. If you are submitting a driver, also read |
15 | Documentation/SubmittingDrivers. |
16 | |
17 | |
18 | |
19 | -------------------------------------------- |
20 | SECTION 1 - CREATING AND SENDING YOUR CHANGE |
21 | -------------------------------------------- |
22 | |
23 | |
24 | |
25 | 1) "diff -up" |
26 | ------------ |
27 | |
28 | Use "diff -up" or "diff -uprN" to create patches. |
29 | |
30 | All changes to the Linux kernel occur in the form of patches, as |
31 | generated by diff(1). When creating your patch, make sure to create it |
32 | in "unified diff" format, as supplied by the '-u' argument to diff(1). |
33 | Also, please use the '-p' argument which shows which C function each |
34 | change is in - that makes the resultant diff a lot easier to read. |
35 | Patches should be based in the root kernel source directory, |
36 | not in any lower subdirectory. |
37 | |
38 | To create a patch for a single file, it is often sufficient to do: |
39 | |
40 | SRCTREE= linux-2.6 |
41 | MYFILE= drivers/net/mydriver.c |
42 | |
43 | cd $SRCTREE |
44 | cp $MYFILE $MYFILE.orig |
45 | vi $MYFILE # make your change |
46 | cd .. |
47 | diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch |
48 | |
49 | To create a patch for multiple files, you should unpack a "vanilla", |
50 | or unmodified kernel source tree, and generate a diff against your |
51 | own source tree. For example: |
52 | |
53 | MYSRC= /devel/linux-2.6 |
54 | |
55 | tar xvfz linux-2.6.12.tar.gz |
56 | mv linux-2.6.12 linux-2.6.12-vanilla |
57 | diff -uprN -X linux-2.6.12-vanilla/Documentation/dontdiff \ |
58 | linux-2.6.12-vanilla $MYSRC > /tmp/patch |
59 | |
60 | "dontdiff" is a list of files which are generated by the kernel during |
61 | the build process, and should be ignored in any diff(1)-generated |
62 | patch. The "dontdiff" file is included in the kernel tree in |
63 | 2.6.12 and later. For earlier kernel versions, you can get it |
64 | from <http://www.xenotime.net/linux/doc/dontdiff>. |
65 | |
66 | Make sure your patch does not include any extra files which do not |
67 | belong in a patch submission. Make sure to review your patch -after- |
68 | generated it with diff(1), to ensure accuracy. |
69 | |
70 | If your changes produce a lot of deltas, you may want to look into |
71 | splitting them into individual patches which modify things in |
72 | logical stages. This will facilitate easier reviewing by other |
73 | kernel developers, very important if you want your patch accepted. |
74 | There are a number of scripts which can aid in this: |
75 | |
76 | Quilt: |
77 | http://savannah.nongnu.org/projects/quilt |
78 | |
79 | Andrew Morton's patch scripts: |
80 | http://userweb.kernel.org/~akpm/stuff/patch-scripts.tar.gz |
81 | Instead of these scripts, quilt is the recommended patch management |
82 | tool (see above). |
83 | |
84 | |
85 | |
86 | 2) Describe your changes. |
87 | |
88 | Describe the technical detail of the change(s) your patch includes. |
89 | |
90 | Be as specific as possible. The WORST descriptions possible include |
91 | things like "update driver X", "bug fix for driver X", or "this patch |
92 | includes updates for subsystem X. Please apply." |
93 | |
94 | The maintainer will thank you if you write your patch description in a |
95 | form which can be easily pulled into Linux's source code management |
96 | system, git, as a "commit log". See #15, below. |
97 | |
98 | If your description starts to get long, that's a sign that you probably |
99 | need to split up your patch. See #3, next. |
100 | |
101 | |
102 | |
103 | 3) Separate your changes. |
104 | |
105 | Separate _logical changes_ into a single patch file. |
106 | |
107 | For example, if your changes include both bug fixes and performance |
108 | enhancements for a single driver, separate those changes into two |
109 | or more patches. If your changes include an API update, and a new |
110 | driver which uses that new API, separate those into two patches. |
111 | |
112 | On the other hand, if you make a single change to numerous files, |
113 | group those changes into a single patch. Thus a single logical change |
114 | is contained within a single patch. |
115 | |
116 | If one patch depends on another patch in order for a change to be |
117 | complete, that is OK. Simply note "this patch depends on patch X" |
118 | in your patch description. |
119 | |
120 | If you cannot condense your patch set into a smaller set of patches, |
121 | then only post say 15 or so at a time and wait for review and integration. |
122 | |
123 | |
124 | |
125 | 4) Style check your changes. |
126 | |
127 | Check your patch for basic style violations, details of which can be |
128 | found in Documentation/CodingStyle. Failure to do so simply wastes |
129 | the reviewers time and will get your patch rejected, probably |
130 | without even being read. |
131 | |
132 | At a minimum you should check your patches with the patch style |
133 | checker prior to submission (scripts/checkpatch.pl). You should |
134 | be able to justify all violations that remain in your patch. |
135 | |
136 | |
137 | |
138 | 5) Select e-mail destination. |
139 | |
140 | Look through the MAINTAINERS file and the source code, and determine |
141 | if your change applies to a specific subsystem of the kernel, with |
142 | an assigned maintainer. If so, e-mail that person. |
143 | |
144 | If no maintainer is listed, or the maintainer does not respond, send |
145 | your patch to the primary Linux kernel developer's mailing list, |
146 | linux-kernel@vger.kernel.org. Most kernel developers monitor this |
147 | e-mail list, and can comment on your changes. |
148 | |
149 | |
150 | Do not send more than 15 patches at once to the vger mailing lists!!! |
151 | |
152 | |
153 | Linus Torvalds is the final arbiter of all changes accepted into the |
154 | Linux kernel. His e-mail address is <torvalds@linux-foundation.org>. |
155 | He gets a lot of e-mail, so typically you should do your best to -avoid- |
156 | sending him e-mail. |
157 | |
158 | Patches which are bug fixes, are "obvious" changes, or similarly |
159 | require little discussion should be sent or CC'd to Linus. Patches |
160 | which require discussion or do not have a clear advantage should |
161 | usually be sent first to linux-kernel. Only after the patch is |
162 | discussed should the patch then be submitted to Linus. |
163 | |
164 | |
165 | |
166 | 6) Select your CC (e-mail carbon copy) list. |
167 | |
168 | Unless you have a reason NOT to do so, CC linux-kernel@vger.kernel.org. |
169 | |
170 | Other kernel developers besides Linus need to be aware of your change, |
171 | so that they may comment on it and offer code review and suggestions. |
172 | linux-kernel is the primary Linux kernel developer mailing list. |
173 | Other mailing lists are available for specific subsystems, such as |
174 | USB, framebuffer devices, the VFS, the SCSI subsystem, etc. See the |
175 | MAINTAINERS file for a mailing list that relates specifically to |
176 | your change. |
177 | |
178 | Majordomo lists of VGER.KERNEL.ORG at: |
179 | <http://vger.kernel.org/vger-lists.html> |
180 | |
181 | If changes affect userland-kernel interfaces, please send |
182 | the MAN-PAGES maintainer (as listed in the MAINTAINERS file) |
183 | a man-pages patch, or at least a notification of the change, |
184 | so that some information makes its way into the manual pages. |
185 | |
186 | Even if the maintainer did not respond in step #5, make sure to ALWAYS |
187 | copy the maintainer when you change their code. |
188 | |
189 | For small patches you may want to CC the Trivial Patch Monkey |
190 | trivial@kernel.org which collects "trivial" patches. Have a look |
191 | into the MAINTAINERS file for its current manager. |
192 | Trivial patches must qualify for one of the following rules: |
193 | Spelling fixes in documentation |
194 | Spelling fixes which could break grep(1) |
195 | Warning fixes (cluttering with useless warnings is bad) |
196 | Compilation fixes (only if they are actually correct) |
197 | Runtime fixes (only if they actually fix things) |
198 | Removing use of deprecated functions/macros (eg. check_region) |
199 | Contact detail and documentation fixes |
200 | Non-portable code replaced by portable code (even in arch-specific, |
201 | since people copy, as long as it's trivial) |
202 | Any fix by the author/maintainer of the file (ie. patch monkey |
203 | in re-transmission mode) |
204 | |
205 | |
206 | |
207 | 7) No MIME, no links, no compression, no attachments. Just plain text. |
208 | |
209 | Linus and other kernel developers need to be able to read and comment |
210 | on the changes you are submitting. It is important for a kernel |
211 | developer to be able to "quote" your changes, using standard e-mail |
212 | tools, so that they may comment on specific portions of your code. |
213 | |
214 | For this reason, all patches should be submitting e-mail "inline". |
215 | WARNING: Be wary of your editor's word-wrap corrupting your patch, |
216 | if you choose to cut-n-paste your patch. |
217 | |
218 | Do not attach the patch as a MIME attachment, compressed or not. |
219 | Many popular e-mail applications will not always transmit a MIME |
220 | attachment as plain text, making it impossible to comment on your |
221 | code. A MIME attachment also takes Linus a bit more time to process, |
222 | decreasing the likelihood of your MIME-attached change being accepted. |
223 | |
224 | Exception: If your mailer is mangling patches then someone may ask |
225 | you to re-send them using MIME. |
226 | |
227 | See Documentation/email-clients.txt for hints about configuring |
228 | your e-mail client so that it sends your patches untouched. |
229 | |
230 | 8) E-mail size. |
231 | |
232 | When sending patches to Linus, always follow step #7. |
233 | |
234 | Large changes are not appropriate for mailing lists, and some |
235 | maintainers. If your patch, uncompressed, exceeds 300 kB in size, |
236 | it is preferred that you store your patch on an Internet-accessible |
237 | server, and provide instead a URL (link) pointing to your patch. |
238 | |
239 | |
240 | |
241 | 9) Name your kernel version. |
242 | |
243 | It is important to note, either in the subject line or in the patch |
244 | description, the kernel version to which this patch applies. |
245 | |
246 | If the patch does not apply cleanly to the latest kernel version, |
247 | Linus will not apply it. |
248 | |
249 | |
250 | |
251 | 10) Don't get discouraged. Re-submit. |
252 | |
253 | After you have submitted your change, be patient and wait. If Linus |
254 | likes your change and applies it, it will appear in the next version |
255 | of the kernel that he releases. |
256 | |
257 | However, if your change doesn't appear in the next version of the |
258 | kernel, there could be any number of reasons. It's YOUR job to |
259 | narrow down those reasons, correct what was wrong, and submit your |
260 | updated change. |
261 | |
262 | It is quite common for Linus to "drop" your patch without comment. |
263 | That's the nature of the system. If he drops your patch, it could be |
264 | due to |
265 | * Your patch did not apply cleanly to the latest kernel version. |
266 | * Your patch was not sufficiently discussed on linux-kernel. |
267 | * A style issue (see section 2). |
268 | * An e-mail formatting issue (re-read this section). |
269 | * A technical problem with your change. |
270 | * He gets tons of e-mail, and yours got lost in the shuffle. |
271 | * You are being annoying. |
272 | |
273 | When in doubt, solicit comments on linux-kernel mailing list. |
274 | |
275 | |
276 | |
277 | 11) Include PATCH in the subject |
278 | |
279 | Due to high e-mail traffic to Linus, and to linux-kernel, it is common |
280 | convention to prefix your subject line with [PATCH]. This lets Linus |
281 | and other kernel developers more easily distinguish patches from other |
282 | e-mail discussions. |
283 | |
284 | |
285 | |
286 | 12) Sign your work |
287 | |
288 | To improve tracking of who did what, especially with patches that can |
289 | percolate to their final resting place in the kernel through several |
290 | layers of maintainers, we've introduced a "sign-off" procedure on |
291 | patches that are being emailed around. |
292 | |
293 | The sign-off is a simple line at the end of the explanation for the |
294 | patch, which certifies that you wrote it or otherwise have the right to |
295 | pass it on as a open-source patch. The rules are pretty simple: if you |
296 | can certify the below: |
297 | |
298 | Developer's Certificate of Origin 1.1 |
299 | |
300 | By making a contribution to this project, I certify that: |
301 | |
302 | (a) The contribution was created in whole or in part by me and I |
303 | have the right to submit it under the open source license |
304 | indicated in the file; or |
305 | |
306 | (b) The contribution is based upon previous work that, to the best |
307 | of my knowledge, is covered under an appropriate open source |
308 | license and I have the right under that license to submit that |
309 | work with modifications, whether created in whole or in part |
310 | by me, under the same open source license (unless I am |
311 | permitted to submit under a different license), as indicated |
312 | in the file; or |
313 | |
314 | (c) The contribution was provided directly to me by some other |
315 | person who certified (a), (b) or (c) and I have not modified |
316 | it. |
317 | |
318 | (d) I understand and agree that this project and the contribution |
319 | are public and that a record of the contribution (including all |
320 | personal information I submit with it, including my sign-off) is |
321 | maintained indefinitely and may be redistributed consistent with |
322 | this project or the open source license(s) involved. |
323 | |
324 | then you just add a line saying |
325 | |
326 | Signed-off-by: Random J Developer <random@developer.example.org> |
327 | |
328 | using your real name (sorry, no pseudonyms or anonymous contributions.) |
329 | |
330 | Some people also put extra tags at the end. They'll just be ignored for |
331 | now, but you can do this to mark internal company procedures or just |
332 | point out some special detail about the sign-off. |
333 | |
334 | If you are a subsystem or branch maintainer, sometimes you need to slightly |
335 | modify patches you receive in order to merge them, because the code is not |
336 | exactly the same in your tree and the submitters'. If you stick strictly to |
337 | rule (c), you should ask the submitter to rediff, but this is a totally |
338 | counter-productive waste of time and energy. Rule (b) allows you to adjust |
339 | the code, but then it is very impolite to change one submitter's code and |
340 | make him endorse your bugs. To solve this problem, it is recommended that |
341 | you add a line between the last Signed-off-by header and yours, indicating |
342 | the nature of your changes. While there is nothing mandatory about this, it |
343 | seems like prepending the description with your mail and/or name, all |
344 | enclosed in square brackets, is noticeable enough to make it obvious that |
345 | you are responsible for last-minute changes. Example : |
346 | |
347 | Signed-off-by: Random J Developer <random@developer.example.org> |
348 | [lucky@maintainer.example.org: struct foo moved from foo.c to foo.h] |
349 | Signed-off-by: Lucky K Maintainer <lucky@maintainer.example.org> |
350 | |
351 | This practise is particularly helpful if you maintain a stable branch and |
352 | want at the same time to credit the author, track changes, merge the fix, |
353 | and protect the submitter from complaints. Note that under no circumstances |
354 | can you change the author's identity (the From header), as it is the one |
355 | which appears in the changelog. |
356 | |
357 | Special note to back-porters: It seems to be a common and useful practise |
358 | to insert an indication of the origin of a patch at the top of the commit |
359 | message (just after the subject line) to facilitate tracking. For instance, |
360 | here's what we see in 2.6-stable : |
361 | |
362 | Date: Tue May 13 19:10:30 2008 +0000 |
363 | |
364 | SCSI: libiscsi regression in 2.6.25: fix nop timer handling |
365 | |
366 | commit 4cf1043593db6a337f10e006c23c69e5fc93e722 upstream |
367 | |
368 | And here's what appears in 2.4 : |
369 | |
370 | Date: Tue May 13 22:12:27 2008 +0200 |
371 | |
372 | wireless, airo: waitbusy() won't delay |
373 | |
374 | [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a] |
375 | |
376 | Whatever the format, this information provides a valuable help to people |
377 | tracking your trees, and to people trying to trouble-shoot bugs in your |
378 | tree. |
379 | |
380 | |
381 | 13) When to use Acked-by: and Cc: |
382 | |
383 | The Signed-off-by: tag indicates that the signer was involved in the |
384 | development of the patch, or that he/she was in the patch's delivery path. |
385 | |
386 | If a person was not directly involved in the preparation or handling of a |
387 | patch but wishes to signify and record their approval of it then they can |
388 | arrange to have an Acked-by: line added to the patch's changelog. |
389 | |
390 | Acked-by: is often used by the maintainer of the affected code when that |
391 | maintainer neither contributed to nor forwarded the patch. |
392 | |
393 | Acked-by: is not as formal as Signed-off-by:. It is a record that the acker |
394 | has at least reviewed the patch and has indicated acceptance. Hence patch |
395 | mergers will sometimes manually convert an acker's "yep, looks good to me" |
396 | into an Acked-by:. |
397 | |
398 | Acked-by: does not necessarily indicate acknowledgement of the entire patch. |
399 | For example, if a patch affects multiple subsystems and has an Acked-by: from |
400 | one subsystem maintainer then this usually indicates acknowledgement of just |
401 | the part which affects that maintainer's code. Judgement should be used here. |
402 | When in doubt people should refer to the original discussion in the mailing |
403 | list archives. |
404 | |
405 | If a person has had the opportunity to comment on a patch, but has not |
406 | provided such comments, you may optionally add a "Cc:" tag to the patch. |
407 | This is the only tag which might be added without an explicit action by the |
408 | person it names. This tag documents that potentially interested parties |
409 | have been included in the discussion |
410 | |
411 | |
412 | 14) Using Reported-by:, Tested-by: and Reviewed-by: |
413 | |
414 | If this patch fixes a problem reported by somebody else, consider adding a |
415 | Reported-by: tag to credit the reporter for their contribution. Please |
416 | note that this tag should not be added without the reporter's permission, |
417 | especially if the problem was not reported in a public forum. That said, |
418 | if we diligently credit our bug reporters, they will, hopefully, be |
419 | inspired to help us again in the future. |
420 | |
421 | A Tested-by: tag indicates that the patch has been successfully tested (in |
422 | some environment) by the person named. This tag informs maintainers that |
423 | some testing has been performed, provides a means to locate testers for |
424 | future patches, and ensures credit for the testers. |
425 | |
426 | Reviewed-by:, instead, indicates that the patch has been reviewed and found |
427 | acceptable according to the Reviewer's Statement: |
428 | |
429 | Reviewer's statement of oversight |
430 | |
431 | By offering my Reviewed-by: tag, I state that: |
432 | |
433 | (a) I have carried out a technical review of this patch to |
434 | evaluate its appropriateness and readiness for inclusion into |
435 | the mainline kernel. |
436 | |
437 | (b) Any problems, concerns, or questions relating to the patch |
438 | have been communicated back to the submitter. I am satisfied |
439 | with the submitter's response to my comments. |
440 | |
441 | (c) While there may be things that could be improved with this |
442 | submission, I believe that it is, at this time, (1) a |
443 | worthwhile modification to the kernel, and (2) free of known |
444 | issues which would argue against its inclusion. |
445 | |
446 | (d) While I have reviewed the patch and believe it to be sound, I |
447 | do not (unless explicitly stated elsewhere) make any |
448 | warranties or guarantees that it will achieve its stated |
449 | purpose or function properly in any given situation. |
450 | |
451 | A Reviewed-by tag is a statement of opinion that the patch is an |
452 | appropriate modification of the kernel without any remaining serious |
453 | technical issues. Any interested reviewer (who has done the work) can |
454 | offer a Reviewed-by tag for a patch. This tag serves to give credit to |
455 | reviewers and to inform maintainers of the degree of review which has been |
456 | done on the patch. Reviewed-by: tags, when supplied by reviewers known to |
457 | understand the subject area and to perform thorough reviews, will normally |
458 | increase the likelihood of your patch getting into the kernel. |
459 | |
460 | |
461 | 15) The canonical patch format |
462 | |
463 | The canonical patch subject line is: |
464 | |
465 | Subject: [PATCH 001/123] subsystem: summary phrase |
466 | |
467 | The canonical patch message body contains the following: |
468 | |
469 | - A "from" line specifying the patch author. |
470 | |
471 | - An empty line. |
472 | |
473 | - The body of the explanation, which will be copied to the |
474 | permanent changelog to describe this patch. |
475 | |
476 | - The "Signed-off-by:" lines, described above, which will |
477 | also go in the changelog. |
478 | |
479 | - A marker line containing simply "---". |
480 | |
481 | - Any additional comments not suitable for the changelog. |
482 | |
483 | - The actual patch (diff output). |
484 | |
485 | The Subject line format makes it very easy to sort the emails |
486 | alphabetically by subject line - pretty much any email reader will |
487 | support that - since because the sequence number is zero-padded, |
488 | the numerical and alphabetic sort is the same. |
489 | |
490 | The "subsystem" in the email's Subject should identify which |
491 | area or subsystem of the kernel is being patched. |
492 | |
493 | The "summary phrase" in the email's Subject should concisely |
494 | describe the patch which that email contains. The "summary |
495 | phrase" should not be a filename. Do not use the same "summary |
496 | phrase" for every patch in a whole patch series (where a "patch |
497 | series" is an ordered sequence of multiple, related patches). |
498 | |
499 | Bear in mind that the "summary phrase" of your email becomes a |
500 | globally-unique identifier for that patch. It propagates all the way |
501 | into the git changelog. The "summary phrase" may later be used in |
502 | developer discussions which refer to the patch. People will want to |
503 | google for the "summary phrase" to read discussion regarding that |
504 | patch. It will also be the only thing that people may quickly see |
505 | when, two or three months later, they are going through perhaps |
506 | thousands of patches using tools such as "gitk" or "git log |
507 | --oneline". |
508 | |
509 | For these reasons, the "summary" must be no more than 70-75 |
510 | characters, and it must describe both what the patch changes, as well |
511 | as why the patch might be necessary. It is challenging to be both |
512 | succinct and descriptive, but that is what a well-written summary |
513 | should do. |
514 | |
515 | The "summary phrase" may be prefixed by tags enclosed in square |
516 | brackets: "Subject: [PATCH tag] <summary phrase>". The tags are not |
517 | considered part of the summary phrase, but describe how the patch |
518 | should be treated. Common tags might include a version descriptor if |
519 | the multiple versions of the patch have been sent out in response to |
520 | comments (i.e., "v1, v2, v3"), or "RFC" to indicate a request for |
521 | comments. If there are four patches in a patch series the individual |
522 | patches may be numbered like this: 1/4, 2/4, 3/4, 4/4. This assures |
523 | that developers understand the order in which the patches should be |
524 | applied and that they have reviewed or applied all of the patches in |
525 | the patch series. |
526 | |
527 | A couple of example Subjects: |
528 | |
529 | Subject: [patch 2/5] ext2: improve scalability of bitmap searching |
530 | Subject: [PATCHv2 001/207] x86: fix eflags tracking |
531 | |
532 | The "from" line must be the very first line in the message body, |
533 | and has the form: |
534 | |
535 | From: Original Author <author@example.com> |
536 | |
537 | The "from" line specifies who will be credited as the author of the |
538 | patch in the permanent changelog. If the "from" line is missing, |
539 | then the "From:" line from the email header will be used to determine |
540 | the patch author in the changelog. |
541 | |
542 | The explanation body will be committed to the permanent source |
543 | changelog, so should make sense to a competent reader who has long |
544 | since forgotten the immediate details of the discussion that might |
545 | have led to this patch. Including symptoms of the failure which the |
546 | patch addresses (kernel log messages, oops messages, etc.) is |
547 | especially useful for people who might be searching the commit logs |
548 | looking for the applicable patch. If a patch fixes a compile failure, |
549 | it may not be necessary to include _all_ of the compile failures; just |
550 | enough that it is likely that someone searching for the patch can find |
551 | it. As in the "summary phrase", it is important to be both succinct as |
552 | well as descriptive. |
553 | |
554 | The "---" marker line serves the essential purpose of marking for patch |
555 | handling tools where the changelog message ends. |
556 | |
557 | One good use for the additional comments after the "---" marker is for |
558 | a diffstat, to show what files have changed, and the number of |
559 | inserted and deleted lines per file. A diffstat is especially useful |
560 | on bigger patches. Other comments relevant only to the moment or the |
561 | maintainer, not suitable for the permanent changelog, should also go |
562 | here. A good example of such comments might be "patch changelogs" |
563 | which describe what has changed between the v1 and v2 version of the |
564 | patch. |
565 | |
566 | If you are going to include a diffstat after the "---" marker, please |
567 | use diffstat options "-p 1 -w 70" so that filenames are listed from |
568 | the top of the kernel source tree and don't use too much horizontal |
569 | space (easily fit in 80 columns, maybe with some indentation). |
570 | |
571 | See more details on the proper patch format in the following |
572 | references. |
573 | |
574 | |
575 | 16) Sending "git pull" requests (from Linus emails) |
576 | |
577 | Please write the git repo address and branch name alone on the same line |
578 | so that I can't even by mistake pull from the wrong branch, and so |
579 | that a triple-click just selects the whole thing. |
580 | |
581 | So the proper format is something along the lines of: |
582 | |
583 | "Please pull from |
584 | |
585 | git://jdelvare.pck.nerim.net/jdelvare-2.6 i2c-for-linus |
586 | |
587 | to get these changes:" |
588 | |
589 | so that I don't have to hunt-and-peck for the address and inevitably |
590 | get it wrong (actually, I've only gotten it wrong a few times, and |
591 | checking against the diffstat tells me when I get it wrong, but I'm |
592 | just a lot more comfortable when I don't have to "look for" the right |
593 | thing to pull, and double-check that I have the right branch-name). |
594 | |
595 | |
596 | Please use "git diff -M --stat --summary" to generate the diffstat: |
597 | the -M enables rename detection, and the summary enables a summary of |
598 | new/deleted or renamed files. |
599 | |
600 | With rename detection, the statistics are rather different [...] |
601 | because git will notice that a fair number of the changes are renames. |
602 | |
603 | ----------------------------------- |
604 | SECTION 2 - HINTS, TIPS, AND TRICKS |
605 | ----------------------------------- |
606 | |
607 | This section lists many of the common "rules" associated with code |
608 | submitted to the kernel. There are always exceptions... but you must |
609 | have a really good reason for doing so. You could probably call this |
610 | section Linus Computer Science 101. |
611 | |
612 | |
613 | |
614 | 1) Read Documentation/CodingStyle |
615 | |
616 | Nuff said. If your code deviates too much from this, it is likely |
617 | to be rejected without further review, and without comment. |
618 | |
619 | One significant exception is when moving code from one file to |
620 | another -- in this case you should not modify the moved code at all in |
621 | the same patch which moves it. This clearly delineates the act of |
622 | moving the code and your changes. This greatly aids review of the |
623 | actual differences and allows tools to better track the history of |
624 | the code itself. |
625 | |
626 | Check your patches with the patch style checker prior to submission |
627 | (scripts/checkpatch.pl). The style checker should be viewed as |
628 | a guide not as the final word. If your code looks better with |
629 | a violation then its probably best left alone. |
630 | |
631 | The checker reports at three levels: |
632 | - ERROR: things that are very likely to be wrong |
633 | - WARNING: things requiring careful review |
634 | - CHECK: things requiring thought |
635 | |
636 | You should be able to justify all violations that remain in your |
637 | patch. |
638 | |
639 | |
640 | |
641 | 2) #ifdefs are ugly |
642 | |
643 | Code cluttered with ifdefs is difficult to read and maintain. Don't do |
644 | it. Instead, put your ifdefs in a header, and conditionally define |
645 | 'static inline' functions, or macros, which are used in the code. |
646 | Let the compiler optimize away the "no-op" case. |
647 | |
648 | Simple example, of poor code: |
649 | |
650 | dev = alloc_etherdev (sizeof(struct funky_private)); |
651 | if (!dev) |
652 | return -ENODEV; |
653 | #ifdef CONFIG_NET_FUNKINESS |
654 | init_funky_net(dev); |
655 | #endif |
656 | |
657 | Cleaned-up example: |
658 | |
659 | (in header) |
660 | #ifndef CONFIG_NET_FUNKINESS |
661 | static inline void init_funky_net (struct net_device *d) {} |
662 | #endif |
663 | |
664 | (in the code itself) |
665 | dev = alloc_etherdev (sizeof(struct funky_private)); |
666 | if (!dev) |
667 | return -ENODEV; |
668 | init_funky_net(dev); |
669 | |
670 | |
671 | |
672 | 3) 'static inline' is better than a macro |
673 | |
674 | Static inline functions are greatly preferred over macros. |
675 | They provide type safety, have no length limitations, no formatting |
676 | limitations, and under gcc they are as cheap as macros. |
677 | |
678 | Macros should only be used for cases where a static inline is clearly |
679 | suboptimal [there are a few, isolated cases of this in fast paths], |
680 | or where it is impossible to use a static inline function [such as |
681 | string-izing]. |
682 | |
683 | 'static inline' is preferred over 'static __inline__', 'extern inline', |
684 | and 'extern __inline__'. |
685 | |
686 | |
687 | |
688 | 4) Don't over-design. |
689 | |
690 | Don't try to anticipate nebulous future cases which may or may not |
691 | be useful: "Make it as simple as you can, and no simpler." |
692 | |
693 | |
694 | |
695 | ---------------------- |
696 | SECTION 3 - REFERENCES |
697 | ---------------------- |
698 | |
699 | Andrew Morton, "The perfect patch" (tpp). |
700 | <http://userweb.kernel.org/~akpm/stuff/tpp.txt> |
701 | |
702 | Jeff Garzik, "Linux kernel patch submission format". |
703 | <http://linux.yyz.us/patch-format.html> |
704 | |
705 | Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer". |
706 | <http://www.kroah.com/log/2005/03/31/> |
707 | <http://www.kroah.com/log/2005/07/08/> |
708 | <http://www.kroah.com/log/2005/10/19/> |
709 | <http://www.kroah.com/log/2006/01/11/> |
710 | |
711 | NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people! |
712 | <http://marc.theaimsgroup.com/?l=linux-kernel&m=112112749912944&w=2> |
713 | |
714 | Kernel Documentation/CodingStyle: |
715 | <http://users.sosdg.org/~qiyong/lxr/source/Documentation/CodingStyle> |
716 | |
717 | Linus Torvalds's mail on the canonical patch format: |
718 | <http://lkml.org/lkml/2005/4/7/183> |
719 | |
720 | Andi Kleen, "On submitting kernel patches" |
721 | Some strategies to get difficult or controversal changes in. |
722 | http://halobates.de/on-submitting-patches.pdf |
723 | |
724 | -- |
725 |
Branches:
ben-wpan
ben-wpan-stefan
javiroman/ks7010
jz-2.6.34
jz-2.6.34-rc5
jz-2.6.34-rc6
jz-2.6.34-rc7
jz-2.6.35
jz-2.6.36
jz-2.6.37
jz-2.6.38
jz-2.6.39
jz-3.0
jz-3.1
jz-3.11
jz-3.12
jz-3.13
jz-3.15
jz-3.16
jz-3.18-dt
jz-3.2
jz-3.3
jz-3.4
jz-3.5
jz-3.6
jz-3.6-rc2-pwm
jz-3.9
jz-3.9-clk
jz-3.9-rc8
jz47xx
jz47xx-2.6.38
master
Tags:
od-2011-09-04
od-2011-09-18
v2.6.34-rc5
v2.6.34-rc6
v2.6.34-rc7
v3.9