Contents of /trunk/mkinitrd-magellan/busybox/docs/contributing.txt
Parent Directory | Revision Log
Revision 984 -
(show annotations)
(download)
Sun May 30 11:32:42 2010 UTC (14 years, 3 months ago) by niro
File MIME type: text/plain
File size: 15605 byte(s)
Sun May 30 11:32:42 2010 UTC (14 years, 3 months ago) by niro
File MIME type: text/plain
File size: 15605 byte(s)
-updated to busybox-1.16.1 and enabled blkid/uuid support in default config
1 | Contributing To Busybox |
2 | ======================= |
3 | |
4 | This document describes what you need to do to contribute to Busybox, where |
5 | you can help, guidelines on testing, and how to submit a well-formed patch |
6 | that is more likely to be accepted. |
7 | |
8 | The Busybox home page is at: http://busybox.net/ |
9 | |
10 | |
11 | |
12 | Pre-Contribution Checklist |
13 | -------------------------- |
14 | |
15 | So you want to contribute to Busybox, eh? Great, wonderful, glad you want to |
16 | help. However, before you dive in, headlong and hotfoot, there are some things |
17 | you need to do: |
18 | |
19 | |
20 | Checkout the Latest Code |
21 | ~~~~~~~~~~~~~~~~~~~~~~~~ |
22 | |
23 | This is a necessary first step. Please do not try to work with the last |
24 | released version, as there is a good chance that somebody has already fixed |
25 | the bug you found. Somebody might have even added the feature you had in mind. |
26 | Don't make your work obsolete before you start! |
27 | |
28 | For information on how to check out Busybox development tree, please look at the |
29 | following links: |
30 | |
31 | http://busybox.net/source.html |
32 | |
33 | |
34 | Read the Mailing List |
35 | ~~~~~~~~~~~~~~~~~~~~~ |
36 | |
37 | No one is required to read the entire archives of the mailing list, but you |
38 | should at least read up on what people have been talking about lately. If |
39 | you've recently discovered a problem, chances are somebody else has too. If |
40 | you're the first to discover a problem, post a message and let the rest of us |
41 | know. |
42 | |
43 | Archives can be found here: |
44 | |
45 | http://busybox.net/lists/busybox/ |
46 | |
47 | If you have a serious interest in Busybox, i.e., you are using it day-to-day or |
48 | as part of an embedded project, it would be a good idea to join the mailing |
49 | list. |
50 | |
51 | A web-based sign-up form can be found here: |
52 | |
53 | http://busybox.net/mailman/listinfo/busybox |
54 | |
55 | |
56 | Coordinate with the Applet Maintainer |
57 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
58 | |
59 | Some (not all) of the applets in Busybox are "owned" by a maintainer who has |
60 | put significant effort into it and is probably more familiar with it than |
61 | others. To find the maintainer of an applet, look at the top of the .c file |
62 | for a name following the word 'Copyright' or 'Written by' or 'Maintainer'. |
63 | |
64 | Before plunging ahead, it's a good idea to send a message to the mailing list |
65 | that says: "Hey, I was thinking about adding the 'transmogrify' feature to the |
66 | 'foo' applet. Would this be useful? Is anyone else working on it?" You might |
67 | want to CC the maintainer (if any) with your question. |
68 | |
69 | |
70 | |
71 | Areas Where You Can Help |
72 | ------------------------ |
73 | |
74 | Busybox can always use improvement! If you're looking for ways to help, there |
75 | are a variety of areas where you could help. |
76 | |
77 | |
78 | What Busybox Doesn't Need |
79 | ~~~~~~~~~~~~~~~~~~~~~~~~~ |
80 | |
81 | Before listing the areas where you _can_ help, it's worthwhile to mention the |
82 | areas where you shouldn't bother. While Busybox strives to be the "Swiss Army |
83 | Knife" of embedded Linux, there are some applets that will not be accepted: |
84 | |
85 | - Any filesystem manipulation tools: Busybox is filesystem independent and |
86 | we do not want to start adding mkfs/fsck tools for every (or any) |
87 | filesystem under the sun. (fsck_minix.c and mkfs_minix.c are living on |
88 | borrowed time.) There are far too many of these tools out there. Use |
89 | the upstream version. Rationale: bugs in these tools can destroy |
90 | vast amounts of data. Keeping up with filesystem format development |
91 | is impractical (especially in the area of keeping fsck tool safe |
92 | and up-to-date). |
93 | |
94 | - Any disk, device, or media-specific tools: Use the -utils or -tools package |
95 | that was designed for your device; don't try to shoehorn them into Busybox. |
96 | |
97 | - Any architecture specific tools: Busybox is (or should be) architecture |
98 | independent. Do not send us tools that cannot be used across multiple |
99 | platforms / arches. |
100 | |
101 | |
102 | Bug Reporting |
103 | ~~~~~~~~~~~~~ |
104 | |
105 | If you find bugs, please submit a detailed bug report to the busybox mailing |
106 | list at busybox@busybox.net. A well-written bug report should include a |
107 | transcript of a shell session that demonstrates the bad behavior and enables |
108 | anyone else to duplicate the bug on their own machine. The following is such |
109 | an example: |
110 | |
111 | To: busybox@busybox.net |
112 | From: diligent@testing.linux.org |
113 | Subject: /bin/date doesn't work |
114 | |
115 | Package: busybox |
116 | Version: 1.00 |
117 | |
118 | When I execute Busybox 'date' it produces unexpected results. |
119 | With GNU date I get the following output: |
120 | |
121 | $ date |
122 | Wed Mar 21 14:19:41 MST 2001 |
123 | |
124 | But when I use BusyBox date I get this instead: |
125 | |
126 | $ date |
127 | Illegal instruction |
128 | |
129 | I am using Debian unstable, kernel version 2.4.19-rmk1 on an Netwinder, |
130 | and the latest uClibc from CVS. |
131 | |
132 | -Diligent |
133 | |
134 | Note the careful description and use of examples showing not only what BusyBox |
135 | does, but also a counter example showing what an equivalent GNU app does. Bug |
136 | reports lacking such detail may never be fixed... Thanks for understanding. |
137 | |
138 | |
139 | |
140 | Write Documentation |
141 | ~~~~~~~~~~~~~~~~~~~ |
142 | |
143 | Chances are, documentation in Busybox is either missing or needs improvement. |
144 | Either way, help is welcome. |
145 | |
146 | Work is being done to automatically generate documentation from sources, |
147 | especially from the usage.h file. If you want to correct the documentation, |
148 | please make changes to the pre-generation parts, rather than the generated |
149 | documentation. [More to come on this later...] |
150 | |
151 | It is preferred that modifications to documentation be submitted in patch |
152 | format (more on this below), but we're a little more lenient when it comes to |
153 | docs. You could, for example, just say "after the listing of the mount |
154 | options, the following example would be helpful..." |
155 | |
156 | |
157 | Consult Existing Sources |
158 | ~~~~~~~~~~~~~~~~~~~~~~~~ |
159 | |
160 | For a quick listing of "needs work" spots in the sources, cd into the Busybox |
161 | directory and run the following: |
162 | |
163 | for i in TODO FIXME XXX; do find -name '*.[ch]'|xargs grep $i; done |
164 | |
165 | This will show all of the trouble spots or 'questionable' code. Pick a spot, |
166 | any spot, these are all invitations for you to contribute. |
167 | |
168 | |
169 | Add a New Applet |
170 | ~~~~~~~~~~~~~~~~ |
171 | |
172 | If you want to add a new applet to Busybox, we'd love to see it. However, |
173 | before you write any code, please ask beforehand on the mailing list something |
174 | like "Do you think applet 'foo' would be useful in Busybox?" or "Would you |
175 | guys accept applet 'foo' into Busybox if I were to write it?" If the answer is |
176 | "no" by the folks on the mailing list, then you've saved yourself some time. |
177 | Conversely, you could get some positive responses from folks who might be |
178 | interested in helping you implement it, or can recommend the best approach. |
179 | Perhaps most importantly, this is your way of calling "dibs" on something and |
180 | avoiding duplication of effort. |
181 | |
182 | Also, before you write a line of code, please read the 'new-applet-HOWTO.txt' |
183 | file in the docs/ directory. |
184 | |
185 | |
186 | Janitorial Work |
187 | ~~~~~~~~~~~~~~~ |
188 | |
189 | These are dirty jobs, but somebody's gotta do 'em. |
190 | |
191 | - Security audits: |
192 | http://www.securityfocus.com/popups/forums/secprog/intro.shtml |
193 | |
194 | - Synthetic code removal: http://www.perl.com/pub/2000/06/commify.html - This |
195 | is very Perl-specific, but the advice given in here applies equally well to |
196 | C. |
197 | |
198 | - C library function use audits: Verifying that functions are being used |
199 | properly (called with the right args), replacing unsafe library functions |
200 | with safer versions, making sure return codes are being checked, etc. |
201 | |
202 | - Where appropriate, replace preprocessor defined macros and values with |
203 | compile-time equivalents. |
204 | |
205 | - Style guide compliance. See: docs/style-guide.txt |
206 | |
207 | - Add testcases to tests/testcases. |
208 | |
209 | - Makefile improvements: |
210 | http://www.canb.auug.org.au/~millerp/rmch/recu-make-cons-harm.html |
211 | (I think the recursive problems are pretty much taken care of at this point, non?) |
212 | |
213 | - "Ten Commandments" compliance: (this is a "maybe", certainly not as |
214 | important as any of the previous items.) |
215 | http://www.lysator.liu.se/c/ten-commandments.html |
216 | |
217 | Other useful links: |
218 | |
219 | - the comp.lang.c FAQ: http://home.datacomm.ch/t_wolf/tw/c/index.html#Sources |
220 | |
221 | |
222 | |
223 | Submitting Patches To Busybox |
224 | ----------------------------- |
225 | |
226 | Here are some guidelines on how to submit a patch to Busybox. |
227 | |
228 | |
229 | Making A Patch |
230 | ~~~~~~~~~~~~~~ |
231 | |
232 | If you've got anonymous CVS access set up, making a patch is simple. Just make |
233 | sure you're in the busybox/ directory and type 'cvs diff -bwu > mychanges.patch'. |
234 | You can send the resulting .patch file to the mailing list with a description |
235 | of what it does. (But not before you test it! See the next section for some |
236 | guidelines.) It is preferred that patches be sent as attachments, but it is |
237 | not required. |
238 | |
239 | Also, feel free to help test other people's patches and reply to them with |
240 | comments. You can apply a patch by saving it into your busybox/ directory and |
241 | typing 'patch < mychanges.patch'. Then you can recompile, see if it runs, test |
242 | if it works as advertised, and post your findings to the mailing list. |
243 | |
244 | NOTE: Please do not include extraneous or irrelevant changes in your patches. |
245 | Please do not try to "bundle" two patches together into one. Make single, |
246 | discreet changes on a per-patch basis. Sometimes you need to make a patch that |
247 | touches code in many places, but these kind of patches are rare and should be |
248 | coordinated with a maintainer. |
249 | |
250 | |
251 | Testing Guidelines |
252 | ~~~~~~~~~~~~~~~~~~ |
253 | |
254 | It's considered good form to test your new feature before you submit a patch |
255 | to the mailing list, and especially before you commit a change to CVS. Here |
256 | are some guidelines on how to test your changes. |
257 | |
258 | - Always test Busybox applets against GNU counterparts and make sure the |
259 | behavior / output is identical between the two. |
260 | |
261 | - Try several different permutations and combinations of the features you're |
262 | adding (i.e., different combinations of command-line switches) and make sure |
263 | they all work; make sure one feature does not interfere with another. |
264 | |
265 | - Make sure you test compiling against the source both with the feature |
266 | turned on and turned off in Config.h and make sure Busybox compiles cleanly |
267 | both ways. |
268 | |
269 | - Run the multibuild.pl script in the tests directory and make sure |
270 | everything checks out OK. (Do this from within the busybox/ directory by |
271 | typing: 'tests/multibuild.pl'.) |
272 | |
273 | |
274 | Making Sure Your Patch Doesn't Get Lost |
275 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
276 | |
277 | If you don't want your patch to be lost or forgotten, send it to the busybox |
278 | mailing list with a subject line something like this: |
279 | |
280 | [PATCH] - Adds "transmogrify" feature to "foo" |
281 | |
282 | In the body, you should have a pseudo-header that looks like the following: |
283 | |
284 | Package: busybox |
285 | Version: v1.01pre (or whatever the current version is) |
286 | Severity: wishlist |
287 | |
288 | The remainder of the body should read along these lines: |
289 | |
290 | This patch adds the "transmogrify" feature to the "foo" applet. I have |
291 | tested this on [arch] system(s) and it works. I have tested it against the |
292 | GNU counterparts and the outputs are identical. I have run the scripts in |
293 | the 'tests' directory and nothing breaks. |
294 | |
295 | |
296 | |
297 | Improving Your Chances of Patch Acceptance |
298 | ------------------------------------------ |
299 | |
300 | Even after you send a brilliant patch to the mailing list, sometimes it can go |
301 | unnoticed, un-replied-to, and sometimes (sigh) even lost. This is an |
302 | unfortunate fact of life, but there are steps you can take to help your patch |
303 | get noticed and convince a maintainer that it should be added: |
304 | |
305 | |
306 | Be Succinct |
307 | ~~~~~~~~~~~ |
308 | |
309 | A patch that includes small, isolated, obvious changes is more likely to be |
310 | accepted than a patch that touches code in lots of different places or makes |
311 | sweeping, dubious changes. |
312 | |
313 | |
314 | Back It Up |
315 | ~~~~~~~~~~ |
316 | |
317 | Hard facts on why your patch is better than the existing code will go a long |
318 | way toward convincing maintainers that your patch should be included. |
319 | Specifically, patches are more likely to be accepted if they are provably more |
320 | correct, smaller, faster, simpler, or more maintainable than the existing |
321 | code. |
322 | |
323 | Conversely, any patch that is supported with nothing more than "I think this |
324 | would be cool" or "this patch is good because I say it is and I've got a Phd |
325 | in Computer Science" will likely be ignored. |
326 | |
327 | |
328 | Follow The Style Guide |
329 | ~~~~~~~~~~~~~~~~~~~~~~ |
330 | |
331 | It's considered good form to abide by the established coding style used in a |
332 | project; Busybox is no exception. We have gone so far as to delineate the |
333 | "elements of Busybox style" in the file docs/style-guide.txt. Please follow |
334 | them. |
335 | |
336 | |
337 | Work With Someone Else |
338 | ~~~~~~~~~~~~~~~~~~~~~~ |
339 | |
340 | Working on a patch in isolation is less effective than working with someone |
341 | else for a variety of reasons. If another Busybox user is interested in what |
342 | you're doing, then it's two (or more) voices instead of one that can petition |
343 | for inclusion of the patch. You'll also have more people that can test your |
344 | changes, or even offer suggestions on better approaches you could take. |
345 | |
346 | Getting other folks interested follows as a natural course if you've received |
347 | responses from queries to applet maintainer or positive responses from folks |
348 | on the mailing list. |
349 | |
350 | We've made strident efforts to put a useful "collaboration" infrastructure in |
351 | place in the form of mailing lists, the bug tracking system, and CVS. Please |
352 | use these resources. |
353 | |
354 | |
355 | Send Patches to the Bug Tracking System |
356 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
357 | |
358 | This was mentioned above in the "Making Sure Your Patch Doesn't Get Lost" |
359 | section, but it is worth mentioning again. A patch sent to the mailing list |
360 | might be unnoticed and forgotten. A patch sent to the bug tracking system will |
361 | be stored and closely connected to the bug it fixes. |
362 | |
363 | |
364 | Be Polite |
365 | ~~~~~~~~~ |
366 | |
367 | The old saying "You'll catch more flies with honey than you will with vinegar" |
368 | applies when submitting patches to the mailing list for approval. The way you |
369 | present your patch is sometimes just as important as the actual patch itself |
370 | (if not more so). Being rude to the maintainers is not an effective way to |
371 | convince them that your patch should be included; it will likely have the |
372 | opposite effect. |
373 | |
374 | |
375 | |
376 | Committing Changes to CVS |
377 | ------------------------- |
378 | |
379 | If you submit several patches that demonstrate that you are a skilled and wise |
380 | coder, you may be invited to become a committer, thus enabling you to commit |
381 | changes directly to CVS. This is nice because you don't have to wait for |
382 | someone else to commit your change for you, you can just do it yourself. |
383 | |
384 | But note that this is a privilege that comes with some responsibilities. You |
385 | should test your changes before you commit them. You should also talk to an |
386 | applet maintainer before you make any kind of sweeping changes to somebody |
387 | else's code. Big changes should still go to the mailing list first. Remember, |
388 | being wise, polite, and discreet is more important than being clever. |
389 | |
390 | |
391 | When To Commit |
392 | ~~~~~~~~~~~~~~ |
393 | |
394 | Generally, you should feel free to commit a change if: |
395 | |
396 | - Your changes are small and don't touch many files |
397 | - You are fixing a bug |
398 | - Somebody has told you that it's okay |
399 | - It's obviously the Right Thing |
400 | |
401 | The more of the above are true, the better it is to just commit a change |
402 | directly to CVS. |
403 | |
404 | |
405 | When Not To Commit |
406 | ~~~~~~~~~~~~~~~~~~ |
407 | |
408 | Even if you have commit rights, you should probably still post a patch to the |
409 | mailing list if: |
410 | |
411 | - Your changes are broad and touch many different files |
412 | - You are adding a feature |
413 | - Your changes are speculative or experimental (i.e., trying a new algorithm) |
414 | - You are not the maintainer and your changes make the maintainer cringe |
415 | |
416 | The more of the above are true, the better it is to post a patch to the |
417 | mailing list instead of committing. |
418 | |
419 | |
420 | |
421 | Final Words |
422 | ----------- |
423 | |
424 | If all of this seems complicated, don't panic, it's really not that tough. If |
425 | you're having difficulty following some of the steps outlined in this |
426 | document don't worry, the folks on the Busybox mailing list are a fairly |
427 | good-natured bunch and will work with you to help get your patches into shape |
428 | or help you make contributions. |
429 | |
430 |