Commit cbd83da82b15292337ff2b71e619c9a3a95f6d80
1 parent
814d8ffd50
Exists in
master
and in
7 other branches
Update DCO ("signoff") rules to 1.1
This adds a clause that notes explicitly that the person doing the sign-off knows that the project (and his sign-off) is public and will possibly get archived and re-distributed.
Showing 1 changed file with 7 additions and 1 deletions Inline Diff
Documentation/SubmittingPatches
1 | 1 | ||
2 | How to Get Your Change Into the Linux Kernel | 2 | How to Get Your Change Into the Linux Kernel |
3 | or | 3 | or |
4 | Care And Operation Of Your Linus Torvalds | 4 | Care And Operation Of Your Linus Torvalds |
5 | 5 | ||
6 | 6 | ||
7 | 7 | ||
8 | For a person or company who wishes to submit a change to the Linux | 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 | 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 | 10 | with "the system." This text is a collection of suggestions which |
11 | can greatly increase the chances of your change being accepted. | 11 | can greatly increase the chances of your change being accepted. |
12 | 12 | ||
13 | If you are submitting a driver, also read Documentation/SubmittingDrivers. | 13 | If you are submitting a driver, also read Documentation/SubmittingDrivers. |
14 | 14 | ||
15 | 15 | ||
16 | 16 | ||
17 | -------------------------------------------- | 17 | -------------------------------------------- |
18 | SECTION 1 - CREATING AND SENDING YOUR CHANGE | 18 | SECTION 1 - CREATING AND SENDING YOUR CHANGE |
19 | -------------------------------------------- | 19 | -------------------------------------------- |
20 | 20 | ||
21 | 21 | ||
22 | 22 | ||
23 | 1) "diff -up" | 23 | 1) "diff -up" |
24 | ------------ | 24 | ------------ |
25 | 25 | ||
26 | Use "diff -up" or "diff -uprN" to create patches. | 26 | Use "diff -up" or "diff -uprN" to create patches. |
27 | 27 | ||
28 | All changes to the Linux kernel occur in the form of patches, as | 28 | All changes to the Linux kernel occur in the form of patches, as |
29 | generated by diff(1). When creating your patch, make sure to create it | 29 | generated by diff(1). When creating your patch, make sure to create it |
30 | in "unified diff" format, as supplied by the '-u' argument to diff(1). | 30 | in "unified diff" format, as supplied by the '-u' argument to diff(1). |
31 | Also, please use the '-p' argument which shows which C function each | 31 | Also, please use the '-p' argument which shows which C function each |
32 | change is in - that makes the resultant diff a lot easier to read. | 32 | change is in - that makes the resultant diff a lot easier to read. |
33 | Patches should be based in the root kernel source directory, | 33 | Patches should be based in the root kernel source directory, |
34 | not in any lower subdirectory. | 34 | not in any lower subdirectory. |
35 | 35 | ||
36 | To create a patch for a single file, it is often sufficient to do: | 36 | To create a patch for a single file, it is often sufficient to do: |
37 | 37 | ||
38 | SRCTREE= linux-2.4 | 38 | SRCTREE= linux-2.4 |
39 | MYFILE= drivers/net/mydriver.c | 39 | MYFILE= drivers/net/mydriver.c |
40 | 40 | ||
41 | cd $SRCTREE | 41 | cd $SRCTREE |
42 | cp $MYFILE $MYFILE.orig | 42 | cp $MYFILE $MYFILE.orig |
43 | vi $MYFILE # make your change | 43 | vi $MYFILE # make your change |
44 | cd .. | 44 | cd .. |
45 | diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch | 45 | diff -up $SRCTREE/$MYFILE{.orig,} > /tmp/patch |
46 | 46 | ||
47 | To create a patch for multiple files, you should unpack a "vanilla", | 47 | To create a patch for multiple files, you should unpack a "vanilla", |
48 | or unmodified kernel source tree, and generate a diff against your | 48 | or unmodified kernel source tree, and generate a diff against your |
49 | own source tree. For example: | 49 | own source tree. For example: |
50 | 50 | ||
51 | MYSRC= /devel/linux-2.4 | 51 | MYSRC= /devel/linux-2.4 |
52 | 52 | ||
53 | tar xvfz linux-2.4.0-test11.tar.gz | 53 | tar xvfz linux-2.4.0-test11.tar.gz |
54 | mv linux linux-vanilla | 54 | mv linux linux-vanilla |
55 | wget http://www.moses.uklinux.net/patches/dontdiff | 55 | wget http://www.moses.uklinux.net/patches/dontdiff |
56 | diff -uprN -X dontdiff linux-vanilla $MYSRC > /tmp/patch | 56 | diff -uprN -X dontdiff linux-vanilla $MYSRC > /tmp/patch |
57 | rm -f dontdiff | 57 | rm -f dontdiff |
58 | 58 | ||
59 | "dontdiff" is a list of files which are generated by the kernel during | 59 | "dontdiff" is a list of files which are generated by the kernel during |
60 | the build process, and should be ignored in any diff(1)-generated | 60 | the build process, and should be ignored in any diff(1)-generated |
61 | patch. dontdiff is maintained by Tigran Aivazian <tigran@veritas.com> | 61 | patch. dontdiff is maintained by Tigran Aivazian <tigran@veritas.com> |
62 | 62 | ||
63 | Make sure your patch does not include any extra files which do not | 63 | Make sure your patch does not include any extra files which do not |
64 | belong in a patch submission. Make sure to review your patch -after- | 64 | belong in a patch submission. Make sure to review your patch -after- |
65 | generated it with diff(1), to ensure accuracy. | 65 | generated it with diff(1), to ensure accuracy. |
66 | 66 | ||
67 | If your changes produce a lot of deltas, you may want to look into | 67 | If your changes produce a lot of deltas, you may want to look into |
68 | splitting them into individual patches which modify things in | 68 | splitting them into individual patches which modify things in |
69 | logical stages, this will facilitate easier reviewing by other | 69 | logical stages, this will facilitate easier reviewing by other |
70 | kernel developers, very important if you want your patch accepted. | 70 | kernel developers, very important if you want your patch accepted. |
71 | There are a number of scripts which can aid in this; | 71 | There are a number of scripts which can aid in this; |
72 | 72 | ||
73 | Quilt: | 73 | Quilt: |
74 | http://savannah.nongnu.org/projects/quilt | 74 | http://savannah.nongnu.org/projects/quilt |
75 | 75 | ||
76 | Randy Dunlap's patch scripts: | 76 | Randy Dunlap's patch scripts: |
77 | http://developer.osdl.org/rddunlap/scripts/patching-scripts.tgz | 77 | http://developer.osdl.org/rddunlap/scripts/patching-scripts.tgz |
78 | 78 | ||
79 | Andrew Morton's patch scripts: | 79 | Andrew Morton's patch scripts: |
80 | http://www.zip.com.au/~akpm/linux/patches/patch-scripts-0.16 | 80 | http://www.zip.com.au/~akpm/linux/patches/patch-scripts-0.16 |
81 | 81 | ||
82 | 2) Describe your changes. | 82 | 2) Describe your changes. |
83 | 83 | ||
84 | Describe the technical detail of the change(s) your patch includes. | 84 | Describe the technical detail of the change(s) your patch includes. |
85 | 85 | ||
86 | Be as specific as possible. The WORST descriptions possible include | 86 | Be as specific as possible. The WORST descriptions possible include |
87 | things like "update driver X", "bug fix for driver X", or "this patch | 87 | things like "update driver X", "bug fix for driver X", or "this patch |
88 | includes updates for subsystem X. Please apply." | 88 | includes updates for subsystem X. Please apply." |
89 | 89 | ||
90 | If your description starts to get long, that's a sign that you probably | 90 | If your description starts to get long, that's a sign that you probably |
91 | need to split up your patch. See #3, next. | 91 | need to split up your patch. See #3, next. |
92 | 92 | ||
93 | 93 | ||
94 | 94 | ||
95 | 3) Separate your changes. | 95 | 3) Separate your changes. |
96 | 96 | ||
97 | Separate each logical change into its own patch. | 97 | Separate each logical change into its own patch. |
98 | 98 | ||
99 | For example, if your changes include both bug fixes and performance | 99 | For example, if your changes include both bug fixes and performance |
100 | enhancements for a single driver, separate those changes into two | 100 | enhancements for a single driver, separate those changes into two |
101 | or more patches. If your changes include an API update, and a new | 101 | or more patches. If your changes include an API update, and a new |
102 | driver which uses that new API, separate those into two patches. | 102 | driver which uses that new API, separate those into two patches. |
103 | 103 | ||
104 | On the other hand, if you make a single change to numerous files, | 104 | On the other hand, if you make a single change to numerous files, |
105 | group those changes into a single patch. Thus a single logical change | 105 | group those changes into a single patch. Thus a single logical change |
106 | is contained within a single patch. | 106 | is contained within a single patch. |
107 | 107 | ||
108 | If one patch depends on another patch in order for a change to be | 108 | If one patch depends on another patch in order for a change to be |
109 | complete, that is OK. Simply note "this patch depends on patch X" | 109 | complete, that is OK. Simply note "this patch depends on patch X" |
110 | in your patch description. | 110 | in your patch description. |
111 | 111 | ||
112 | 112 | ||
113 | 4) Select e-mail destination. | 113 | 4) Select e-mail destination. |
114 | 114 | ||
115 | Look through the MAINTAINERS file and the source code, and determine | 115 | Look through the MAINTAINERS file and the source code, and determine |
116 | if your change applies to a specific subsystem of the kernel, with | 116 | if your change applies to a specific subsystem of the kernel, with |
117 | an assigned maintainer. If so, e-mail that person. | 117 | an assigned maintainer. If so, e-mail that person. |
118 | 118 | ||
119 | If no maintainer is listed, or the maintainer does not respond, send | 119 | If no maintainer is listed, or the maintainer does not respond, send |
120 | your patch to the primary Linux kernel developer's mailing list, | 120 | your patch to the primary Linux kernel developer's mailing list, |
121 | linux-kernel@vger.kernel.org. Most kernel developers monitor this | 121 | linux-kernel@vger.kernel.org. Most kernel developers monitor this |
122 | e-mail list, and can comment on your changes. | 122 | e-mail list, and can comment on your changes. |
123 | 123 | ||
124 | Linus Torvalds is the final arbiter of all changes accepted into the | 124 | Linus Torvalds is the final arbiter of all changes accepted into the |
125 | Linux kernel. His e-mail address is <torvalds@osdl.org>. He gets | 125 | Linux kernel. His e-mail address is <torvalds@osdl.org>. He gets |
126 | a lot of e-mail, so typically you should do your best to -avoid- sending | 126 | a lot of e-mail, so typically you should do your best to -avoid- sending |
127 | him e-mail. | 127 | him e-mail. |
128 | 128 | ||
129 | Patches which are bug fixes, are "obvious" changes, or similarly | 129 | Patches which are bug fixes, are "obvious" changes, or similarly |
130 | require little discussion should be sent or CC'd to Linus. Patches | 130 | require little discussion should be sent or CC'd to Linus. Patches |
131 | which require discussion or do not have a clear advantage should | 131 | which require discussion or do not have a clear advantage should |
132 | usually be sent first to linux-kernel. Only after the patch is | 132 | usually be sent first to linux-kernel. Only after the patch is |
133 | discussed should the patch then be submitted to Linus. | 133 | discussed should the patch then be submitted to Linus. |
134 | 134 | ||
135 | For small patches you may want to CC the Trivial Patch Monkey | 135 | For small patches you may want to CC the Trivial Patch Monkey |
136 | trivial@rustcorp.com.au set up by Rusty Russell; which collects "trivial" | 136 | trivial@rustcorp.com.au set up by Rusty Russell; which collects "trivial" |
137 | patches. Trivial patches must qualify for one of the following rules: | 137 | patches. Trivial patches must qualify for one of the following rules: |
138 | Spelling fixes in documentation | 138 | Spelling fixes in documentation |
139 | Spelling fixes which could break grep(1). | 139 | Spelling fixes which could break grep(1). |
140 | Warning fixes (cluttering with useless warnings is bad) | 140 | Warning fixes (cluttering with useless warnings is bad) |
141 | Compilation fixes (only if they are actually correct) | 141 | Compilation fixes (only if they are actually correct) |
142 | Runtime fixes (only if they actually fix things) | 142 | Runtime fixes (only if they actually fix things) |
143 | Removing use of deprecated functions/macros (eg. check_region). | 143 | Removing use of deprecated functions/macros (eg. check_region). |
144 | Contact detail and documentation fixes | 144 | Contact detail and documentation fixes |
145 | Non-portable code replaced by portable code (even in arch-specific, | 145 | Non-portable code replaced by portable code (even in arch-specific, |
146 | since people copy, as long as it's trivial) | 146 | since people copy, as long as it's trivial) |
147 | Any fix by the author/maintainer of the file. (ie. patch monkey | 147 | Any fix by the author/maintainer of the file. (ie. patch monkey |
148 | in re-transmission mode) | 148 | in re-transmission mode) |
149 | 149 | ||
150 | 150 | ||
151 | 151 | ||
152 | 5) Select your CC (e-mail carbon copy) list. | 152 | 5) Select your CC (e-mail carbon copy) list. |
153 | 153 | ||
154 | Unless you have a reason NOT to do so, CC linux-kernel@vger.kernel.org. | 154 | Unless you have a reason NOT to do so, CC linux-kernel@vger.kernel.org. |
155 | 155 | ||
156 | Other kernel developers besides Linus need to be aware of your change, | 156 | Other kernel developers besides Linus need to be aware of your change, |
157 | so that they may comment on it and offer code review and suggestions. | 157 | so that they may comment on it and offer code review and suggestions. |
158 | linux-kernel is the primary Linux kernel developer mailing list. | 158 | linux-kernel is the primary Linux kernel developer mailing list. |
159 | Other mailing lists are available for specific subsystems, such as | 159 | Other mailing lists are available for specific subsystems, such as |
160 | USB, framebuffer devices, the VFS, the SCSI subsystem, etc. See the | 160 | USB, framebuffer devices, the VFS, the SCSI subsystem, etc. See the |
161 | MAINTAINERS file for a mailing list that relates specifically to | 161 | MAINTAINERS file for a mailing list that relates specifically to |
162 | your change. | 162 | your change. |
163 | 163 | ||
164 | Even if the maintainer did not respond in step #4, make sure to ALWAYS | 164 | Even if the maintainer did not respond in step #4, make sure to ALWAYS |
165 | copy the maintainer when you change their code. | 165 | copy the maintainer when you change their code. |
166 | 166 | ||
167 | For small patches you may want to CC the Trivial Patch Monkey | 167 | For small patches you may want to CC the Trivial Patch Monkey |
168 | trivial@rustcorp.com.au set up by Rusty Russell; which collects "trivial" | 168 | trivial@rustcorp.com.au set up by Rusty Russell; which collects "trivial" |
169 | patches. Trivial patches must qualify for one of the following rules: | 169 | patches. Trivial patches must qualify for one of the following rules: |
170 | Spelling fixes in documentation | 170 | Spelling fixes in documentation |
171 | Spelling fixes which could break grep(1). | 171 | Spelling fixes which could break grep(1). |
172 | Warning fixes (cluttering with useless warnings is bad) | 172 | Warning fixes (cluttering with useless warnings is bad) |
173 | Compilation fixes (only if they are actually correct) | 173 | Compilation fixes (only if they are actually correct) |
174 | Runtime fixes (only if they actually fix things) | 174 | Runtime fixes (only if they actually fix things) |
175 | Removing use of deprecated functions/macros (eg. check_region). | 175 | Removing use of deprecated functions/macros (eg. check_region). |
176 | Contact detail and documentation fixes | 176 | Contact detail and documentation fixes |
177 | Non-portable code replaced by portable code (even in arch-specific, | 177 | Non-portable code replaced by portable code (even in arch-specific, |
178 | since people copy, as long as it's trivial) | 178 | since people copy, as long as it's trivial) |
179 | Any fix by the author/maintainer of the file. (ie. patch monkey | 179 | Any fix by the author/maintainer of the file. (ie. patch monkey |
180 | in re-transmission mode) | 180 | in re-transmission mode) |
181 | 181 | ||
182 | 182 | ||
183 | 183 | ||
184 | 6) No MIME, no links, no compression, no attachments. Just plain text. | 184 | 6) No MIME, no links, no compression, no attachments. Just plain text. |
185 | 185 | ||
186 | Linus and other kernel developers need to be able to read and comment | 186 | Linus and other kernel developers need to be able to read and comment |
187 | on the changes you are submitting. It is important for a kernel | 187 | on the changes you are submitting. It is important for a kernel |
188 | developer to be able to "quote" your changes, using standard e-mail | 188 | developer to be able to "quote" your changes, using standard e-mail |
189 | tools, so that they may comment on specific portions of your code. | 189 | tools, so that they may comment on specific portions of your code. |
190 | 190 | ||
191 | For this reason, all patches should be submitting e-mail "inline". | 191 | For this reason, all patches should be submitting e-mail "inline". |
192 | WARNING: Be wary of your editor's word-wrap corrupting your patch, | 192 | WARNING: Be wary of your editor's word-wrap corrupting your patch, |
193 | if you choose to cut-n-paste your patch. | 193 | if you choose to cut-n-paste your patch. |
194 | 194 | ||
195 | Do not attach the patch as a MIME attachment, compressed or not. | 195 | Do not attach the patch as a MIME attachment, compressed or not. |
196 | Many popular e-mail applications will not always transmit a MIME | 196 | Many popular e-mail applications will not always transmit a MIME |
197 | attachment as plain text, making it impossible to comment on your | 197 | attachment as plain text, making it impossible to comment on your |
198 | code. A MIME attachment also takes Linus a bit more time to process, | 198 | code. A MIME attachment also takes Linus a bit more time to process, |
199 | decreasing the likelihood of your MIME-attached change being accepted. | 199 | decreasing the likelihood of your MIME-attached change being accepted. |
200 | 200 | ||
201 | Exception: If your mailer is mangling patches then someone may ask | 201 | Exception: If your mailer is mangling patches then someone may ask |
202 | you to re-send them using MIME. | 202 | you to re-send them using MIME. |
203 | 203 | ||
204 | 204 | ||
205 | 205 | ||
206 | 7) E-mail size. | 206 | 7) E-mail size. |
207 | 207 | ||
208 | When sending patches to Linus, always follow step #6. | 208 | When sending patches to Linus, always follow step #6. |
209 | 209 | ||
210 | Large changes are not appropriate for mailing lists, and some | 210 | Large changes are not appropriate for mailing lists, and some |
211 | maintainers. If your patch, uncompressed, exceeds 40 kB in size, | 211 | maintainers. If your patch, uncompressed, exceeds 40 kB in size, |
212 | it is preferred that you store your patch on an Internet-accessible | 212 | it is preferred that you store your patch on an Internet-accessible |
213 | server, and provide instead a URL (link) pointing to your patch. | 213 | server, and provide instead a URL (link) pointing to your patch. |
214 | 214 | ||
215 | 215 | ||
216 | 216 | ||
217 | 8) Name your kernel version. | 217 | 8) Name your kernel version. |
218 | 218 | ||
219 | It is important to note, either in the subject line or in the patch | 219 | It is important to note, either in the subject line or in the patch |
220 | description, the kernel version to which this patch applies. | 220 | description, the kernel version to which this patch applies. |
221 | 221 | ||
222 | If the patch does not apply cleanly to the latest kernel version, | 222 | If the patch does not apply cleanly to the latest kernel version, |
223 | Linus will not apply it. | 223 | Linus will not apply it. |
224 | 224 | ||
225 | 225 | ||
226 | 226 | ||
227 | 9) Don't get discouraged. Re-submit. | 227 | 9) Don't get discouraged. Re-submit. |
228 | 228 | ||
229 | After you have submitted your change, be patient and wait. If Linus | 229 | After you have submitted your change, be patient and wait. If Linus |
230 | likes your change and applies it, it will appear in the next version | 230 | likes your change and applies it, it will appear in the next version |
231 | of the kernel that he releases. | 231 | of the kernel that he releases. |
232 | 232 | ||
233 | However, if your change doesn't appear in the next version of the | 233 | However, if your change doesn't appear in the next version of the |
234 | kernel, there could be any number of reasons. It's YOUR job to | 234 | kernel, there could be any number of reasons. It's YOUR job to |
235 | narrow down those reasons, correct what was wrong, and submit your | 235 | narrow down those reasons, correct what was wrong, and submit your |
236 | updated change. | 236 | updated change. |
237 | 237 | ||
238 | It is quite common for Linus to "drop" your patch without comment. | 238 | It is quite common for Linus to "drop" your patch without comment. |
239 | That's the nature of the system. If he drops your patch, it could be | 239 | That's the nature of the system. If he drops your patch, it could be |
240 | due to | 240 | due to |
241 | * Your patch did not apply cleanly to the latest kernel version | 241 | * Your patch did not apply cleanly to the latest kernel version |
242 | * Your patch was not sufficiently discussed on linux-kernel. | 242 | * Your patch was not sufficiently discussed on linux-kernel. |
243 | * A style issue (see section 2), | 243 | * A style issue (see section 2), |
244 | * An e-mail formatting issue (re-read this section) | 244 | * An e-mail formatting issue (re-read this section) |
245 | * A technical problem with your change | 245 | * A technical problem with your change |
246 | * He gets tons of e-mail, and yours got lost in the shuffle | 246 | * He gets tons of e-mail, and yours got lost in the shuffle |
247 | * You are being annoying (See Figure 1) | 247 | * You are being annoying (See Figure 1) |
248 | 248 | ||
249 | When in doubt, solicit comments on linux-kernel mailing list. | 249 | When in doubt, solicit comments on linux-kernel mailing list. |
250 | 250 | ||
251 | 251 | ||
252 | 252 | ||
253 | 10) Include PATCH in the subject | 253 | 10) Include PATCH in the subject |
254 | 254 | ||
255 | Due to high e-mail traffic to Linus, and to linux-kernel, it is common | 255 | Due to high e-mail traffic to Linus, and to linux-kernel, it is common |
256 | convention to prefix your subject line with [PATCH]. This lets Linus | 256 | convention to prefix your subject line with [PATCH]. This lets Linus |
257 | and other kernel developers more easily distinguish patches from other | 257 | and other kernel developers more easily distinguish patches from other |
258 | e-mail discussions. | 258 | e-mail discussions. |
259 | 259 | ||
260 | 260 | ||
261 | 261 | ||
262 | 11) Sign your work | 262 | 11) Sign your work |
263 | 263 | ||
264 | To improve tracking of who did what, especially with patches that can | 264 | To improve tracking of who did what, especially with patches that can |
265 | percolate to their final resting place in the kernel through several | 265 | percolate to their final resting place in the kernel through several |
266 | layers of maintainers, we've introduced a "sign-off" procedure on | 266 | layers of maintainers, we've introduced a "sign-off" procedure on |
267 | patches that are being emailed around. | 267 | patches that are being emailed around. |
268 | 268 | ||
269 | The sign-off is a simple line at the end of the explanation for the | 269 | The sign-off is a simple line at the end of the explanation for the |
270 | patch, which certifies that you wrote it or otherwise have the right to | 270 | patch, which certifies that you wrote it or otherwise have the right to |
271 | pass it on as a open-source patch. The rules are pretty simple: if you | 271 | pass it on as a open-source patch. The rules are pretty simple: if you |
272 | can certify the below: | 272 | can certify the below: |
273 | 273 | ||
274 | Developer's Certificate of Origin 1.0 | 274 | Developer's Certificate of Origin 1.1 |
275 | 275 | ||
276 | By making a contribution to this project, I certify that: | 276 | By making a contribution to this project, I certify that: |
277 | 277 | ||
278 | (a) The contribution was created in whole or in part by me and I | 278 | (a) The contribution was created in whole or in part by me and I |
279 | have the right to submit it under the open source license | 279 | have the right to submit it under the open source license |
280 | indicated in the file; or | 280 | indicated in the file; or |
281 | 281 | ||
282 | (b) The contribution is based upon previous work that, to the best | 282 | (b) The contribution is based upon previous work that, to the best |
283 | of my knowledge, is covered under an appropriate open source | 283 | of my knowledge, is covered under an appropriate open source |
284 | license and I have the right under that license to submit that | 284 | license and I have the right under that license to submit that |
285 | work with modifications, whether created in whole or in part | 285 | work with modifications, whether created in whole or in part |
286 | by me, under the same open source license (unless I am | 286 | by me, under the same open source license (unless I am |
287 | permitted to submit under a different license), as indicated | 287 | permitted to submit under a different license), as indicated |
288 | in the file; or | 288 | in the file; or |
289 | 289 | ||
290 | (c) The contribution was provided directly to me by some other | 290 | (c) The contribution was provided directly to me by some other |
291 | person who certified (a), (b) or (c) and I have not modified | 291 | person who certified (a), (b) or (c) and I have not modified |
292 | it. | 292 | it. |
293 | |||
294 | (d) I understand and agree that this project and the contribution | ||
295 | are public and that a record of the contribution (including all | ||
296 | personal information I submit with it, including my sign-off) is | ||
297 | maintained indefinitely and may be redistributed consistent with | ||
298 | this project or the open source license(s) involved. | ||
293 | 299 | ||
294 | then you just add a line saying | 300 | then you just add a line saying |
295 | 301 | ||
296 | Signed-off-by: Random J Developer <random@developer.org> | 302 | Signed-off-by: Random J Developer <random@developer.org> |
297 | 303 | ||
298 | Some people also put extra tags at the end. They'll just be ignored for | 304 | Some people also put extra tags at the end. They'll just be ignored for |
299 | now, but you can do this to mark internal company procedures or just | 305 | now, but you can do this to mark internal company procedures or just |
300 | point out some special detail about the sign-off. | 306 | point out some special detail about the sign-off. |
301 | 307 | ||
302 | 308 | ||
303 | ----------------------------------- | 309 | ----------------------------------- |
304 | SECTION 2 - HINTS, TIPS, AND TRICKS | 310 | SECTION 2 - HINTS, TIPS, AND TRICKS |
305 | ----------------------------------- | 311 | ----------------------------------- |
306 | 312 | ||
307 | This section lists many of the common "rules" associated with code | 313 | This section lists many of the common "rules" associated with code |
308 | submitted to the kernel. There are always exceptions... but you must | 314 | submitted to the kernel. There are always exceptions... but you must |
309 | have a really good reason for doing so. You could probably call this | 315 | have a really good reason for doing so. You could probably call this |
310 | section Linus Computer Science 101. | 316 | section Linus Computer Science 101. |
311 | 317 | ||
312 | 318 | ||
313 | 319 | ||
314 | 1) Read Documentation/CodingStyle | 320 | 1) Read Documentation/CodingStyle |
315 | 321 | ||
316 | Nuff said. If your code deviates too much from this, it is likely | 322 | Nuff said. If your code deviates too much from this, it is likely |
317 | to be rejected without further review, and without comment. | 323 | to be rejected without further review, and without comment. |
318 | 324 | ||
319 | 325 | ||
320 | 326 | ||
321 | 2) #ifdefs are ugly | 327 | 2) #ifdefs are ugly |
322 | 328 | ||
323 | Code cluttered with ifdefs is difficult to read and maintain. Don't do | 329 | Code cluttered with ifdefs is difficult to read and maintain. Don't do |
324 | it. Instead, put your ifdefs in a header, and conditionally define | 330 | it. Instead, put your ifdefs in a header, and conditionally define |
325 | 'static inline' functions, or macros, which are used in the code. | 331 | 'static inline' functions, or macros, which are used in the code. |
326 | Let the compiler optimize away the "no-op" case. | 332 | Let the compiler optimize away the "no-op" case. |
327 | 333 | ||
328 | Simple example, of poor code: | 334 | Simple example, of poor code: |
329 | 335 | ||
330 | dev = alloc_etherdev (sizeof(struct funky_private)); | 336 | dev = alloc_etherdev (sizeof(struct funky_private)); |
331 | if (!dev) | 337 | if (!dev) |
332 | return -ENODEV; | 338 | return -ENODEV; |
333 | #ifdef CONFIG_NET_FUNKINESS | 339 | #ifdef CONFIG_NET_FUNKINESS |
334 | init_funky_net(dev); | 340 | init_funky_net(dev); |
335 | #endif | 341 | #endif |
336 | 342 | ||
337 | Cleaned-up example: | 343 | Cleaned-up example: |
338 | 344 | ||
339 | (in header) | 345 | (in header) |
340 | #ifndef CONFIG_NET_FUNKINESS | 346 | #ifndef CONFIG_NET_FUNKINESS |
341 | static inline void init_funky_net (struct net_device *d) {} | 347 | static inline void init_funky_net (struct net_device *d) {} |
342 | #endif | 348 | #endif |
343 | 349 | ||
344 | (in the code itself) | 350 | (in the code itself) |
345 | dev = alloc_etherdev (sizeof(struct funky_private)); | 351 | dev = alloc_etherdev (sizeof(struct funky_private)); |
346 | if (!dev) | 352 | if (!dev) |
347 | return -ENODEV; | 353 | return -ENODEV; |
348 | init_funky_net(dev); | 354 | init_funky_net(dev); |
349 | 355 | ||
350 | 356 | ||
351 | 357 | ||
352 | 3) 'static inline' is better than a macro | 358 | 3) 'static inline' is better than a macro |
353 | 359 | ||
354 | Static inline functions are greatly preferred over macros. | 360 | Static inline functions are greatly preferred over macros. |
355 | They provide type safety, have no length limitations, no formatting | 361 | They provide type safety, have no length limitations, no formatting |
356 | limitations, and under gcc they are as cheap as macros. | 362 | limitations, and under gcc they are as cheap as macros. |
357 | 363 | ||
358 | Macros should only be used for cases where a static inline is clearly | 364 | Macros should only be used for cases where a static inline is clearly |
359 | suboptimal [there a few, isolated cases of this in fast paths], | 365 | suboptimal [there a few, isolated cases of this in fast paths], |
360 | or where it is impossible to use a static inline function [such as | 366 | or where it is impossible to use a static inline function [such as |
361 | string-izing]. | 367 | string-izing]. |
362 | 368 | ||
363 | 'static inline' is preferred over 'static __inline__', 'extern inline', | 369 | 'static inline' is preferred over 'static __inline__', 'extern inline', |
364 | and 'extern __inline__'. | 370 | and 'extern __inline__'. |
365 | 371 | ||
366 | 372 | ||
367 | 373 | ||
368 | 4) Don't over-design. | 374 | 4) Don't over-design. |
369 | 375 | ||
370 | Don't try to anticipate nebulous future cases which may or may not | 376 | Don't try to anticipate nebulous future cases which may or may not |
371 | be useful: "Make it as simple as you can, and no simpler" | 377 | be useful: "Make it as simple as you can, and no simpler" |
372 | 378 | ||
373 | 379 | ||
374 | 380 | ||
375 | 381 |