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