source: branches/2.2.9/mindi-busybox/docs/contributing.txt @ 2142

Last change on this file since 2142 was 821, checked in by Bruno Cornec, 14 years ago

Addition of busybox 1.2.1 as a mindi-busybox new package
This should avoid delivering binary files in mindi not built there (Fedora and Debian are quite serious about that)

File size: 16.4 KB
Line 
1Contributing To Busybox
2=======================
3
4This document describes what you need to do to contribute to Busybox, where
5you can help, guidelines on testing, and how to submit a well-formed patch
6that is more likely to be accepted.
7
8The Busybox home page is at: http://busybox.net/
9
10
11
12Pre-Contribution Checklist
13--------------------------
14
15So you want to contribute to Busybox, eh? Great, wonderful, glad you want to
16help. However, before you dive in, headlong and hotfoot, there are some things
17you need to do:
18
19
20Checkout the Latest Code from CVS
21~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
22
23This is a necessary first step. Please do not try to work with the last
24released version, as there is a good chance that somebody has already fixed
25the bug you found. Somebody might have even added the feature you had in mind.
26Don't make your work obsolete before you start!
27
28For information on how to check out Busybox from CVS, please look at the
29following links:
30
31    http://busybox.net/cvs_anon.html
32    http://busybox.net/cvs_howto.html
33
34
35Read the Mailing List
36~~~~~~~~~~~~~~~~~~~~~
37
38No one is required to read the entire archives of the mailing list, but you
39should at least read up on what people have been talking about lately. If
40you've recently discovered a problem, chances are somebody else has too. If
41you're the first to discover a problem, post a message and let the rest of us
42know.
43
44Archives can be found here:
45
46    http://busybox.net/lists/busybox/
47
48If you have a serious interest in Busybox, i.e., you are using it day-to-day or
49as part of an embedded project, it would be a good idea to join the mailing
50list.
51
52A web-based sign-up form can be found here:
53
54    http://busybox.net/mailman/listinfo/busybox
55
56
57Coordinate with the Applet Maintainer
58~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
59
60Some (not all) of the applets in Busybox are "owned" by a maintainer who has
61put significant effort into it and is probably more familiar with it than
62others. To find the maintainer of an applet, look at the top of the .c file
63for a name following the word 'Copyright' or 'Written by' or 'Maintainer'.
64
65Before plunging ahead, it's a good idea to send a message to the mailing list
66that 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
68want to CC the maintainer (if any) with your question.
69
70
71
72Areas Where You Can Help
73------------------------
74
75Busybox can always use improvement! If you're looking for ways to help, there
76are a variety of areas where you could help.
77
78
79What Busybox Doesn't Need
80~~~~~~~~~~~~~~~~~~~~~~~~~
81
82Before listing the areas where you _can_ help, it's worthwhile to mention the
83areas where you shouldn't bother. While Busybox strives to be the "Swiss Army
84Knife" 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
113Bug Reporting
114~~~~~~~~~~~~~
115
116If you find bugs, please submit a detailed bug report to the busybox mailing
117list at busybox@busybox.net.  A well-written bug report should include a
118transcript of a shell session that demonstrates the bad behavior and enables
119anyone else to duplicate the bug on their own machine. The following is such
120an 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
145Note the careful description and use of examples showing not only what BusyBox
146does, but also a counter example showing what an equivalent GNU app does.  Bug
147reports lacking such detail may never be fixed...  Thanks for understanding.
148
149
150
151Write Documentation
152~~~~~~~~~~~~~~~~~~~
153
154Chances are, documentation in Busybox is either missing or needs improvement.
155Either way, help is welcome.
156
157Work is being done to automatically generate documentation from sources,
158especially from the usage.h file. If you want to correct the documentation,
159please make changes to the pre-generation parts, rather than the generated
160documentation. [More to come on this later...]
161
162It is preferred that modifications to documentation be submitted in patch
163format (more on this below), but we're a little more lenient when it comes to
164docs. You could, for example, just say "after the listing of the mount
165options, the following example would be helpful..."
166
167
168Consult Existing Sources
169~~~~~~~~~~~~~~~~~~~~~~~~
170
171For a quick listing of "needs work" spots in the sources, cd into the Busybox
172directory and run the following:
173
174    for i in TODO FIXME XXX; do find -name '*.[ch]'|xargs grep $i; done
175
176This will show all of the trouble spots or 'questionable' code. Pick a spot,
177any spot, these are all invitations for you to contribute.
178
179
180Add a New Applet
181~~~~~~~~~~~~~~~~
182
183If you want to add a new applet to Busybox, we'd love to see it. However,
184before you write any code, please ask beforehand on the mailing list something
185like "Do you think applet 'foo' would be useful in Busybox?" or "Would you
186guys 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.
188Conversely, you could get some positive responses from folks who might be
189interested in helping you implement it, or can recommend the best approach.
190Perhaps most importantly, this is your way of calling "dibs" on something and
191avoiding duplication of effort.
192
193Also, before you write a line of code, please read the 'new-applet-HOWTO.txt'
194file in the docs/ directory.
195
196
197Janitorial Work
198~~~~~~~~~~~~~~~
199
200These 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
236Other useful links:
237
238 - the comp.lang.c FAQ: http://web.onetelnet.ch/~twolf/tw/c/index.html#Sources
239
240
241
242Submitting Patches To Busybox
243-----------------------------
244
245Here are some guidelines on how to submit a patch to Busybox.
246
247
248Making A Patch
249~~~~~~~~~~~~~~
250
251If you've got anonymous CVS access set up, making a patch is simple. Just make
252sure you're in the busybox/ directory and type 'cvs diff -bwu > mychanges.patch'.
253You can send the resulting .patch file to the mailing list with a description
254of what it does. (But not before you test it! See the next section for some
255guidelines.) It is preferred that patches be sent as attachments, but it is
256not required.
257
258Also, feel free to help test other people's patches and reply to them with
259comments. You can apply a patch by saving it into your busybox/ directory and
260typing 'patch < mychanges.patch'. Then you can recompile, see if it runs, test
261if it works as advertised, and post your findings to the mailing list.
262
263NOTE: Please do not include extraneous or irrelevant changes in your patches.
264Please do not try to "bundle" two patches together into one. Make single,
265discreet changes on a per-patch basis. Sometimes you need to make a patch that
266touches code in many places, but these kind of patches are rare and should be
267coordinated with a maintainer.
268
269
270Testing Guidelines
271~~~~~~~~~~~~~~~~~~
272
273It's considered good form to test your new feature before you submit a patch
274to the mailing list, and especially before you commit a change to CVS. Here
275are 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
293Making Sure Your Patch Doesn't Get Lost
294~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
295
296If you don't want your patch to be lost or forgotten, send it to the busybox
297mailing list with a subject line something like this:
298
299    [PATCH] - Adds "transmogrify" feature to "foo"
300
301In 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
307The 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
316Improving Your Chances of Patch Acceptance
317------------------------------------------
318
319Even after you send a brilliant patch to the mailing list, sometimes it can go
320unnoticed, un-replied-to, and sometimes (sigh) even lost. This is an
321unfortunate fact of life, but there are steps you can take to help your patch
322get noticed and convince a maintainer that it should be added:
323
324
325Be Succinct
326~~~~~~~~~~~
327
328A patch that includes small, isolated, obvious changes is more likely to be
329accepted than a patch that touches code in lots of different places or makes
330sweeping, dubious changes.
331
332
333Back It Up
334~~~~~~~~~~
335
336Hard facts on why your patch is better than the existing code will go a long
337way toward convincing maintainers that your patch should be included.
338Specifically, patches are more likely to be accepted if they are provably more
339correct, smaller, faster, simpler, or more maintainable than the existing
340code.
341
342Conversely, any patch that is supported with nothing more than "I think this
343would be cool" or "this patch is good because I say it is and I've got a Phd
344in Computer Science" will likely be ignored.
345
346
347Follow The Style Guide
348~~~~~~~~~~~~~~~~~~~~~~
349
350It's considered good form to abide by the established coding style used in a
351project; 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
353them.
354
355
356Work With Someone Else
357~~~~~~~~~~~~~~~~~~~~~~
358
359Working on a patch in isolation is less effective than working with someone
360else for a variety of reasons. If another Busybox user is interested in what
361you're doing, then it's two (or more) voices instead of one that can petition
362for inclusion of the patch. You'll also have more people that can test your
363changes, or even offer suggestions on better approaches you could take.
364
365Getting other folks interested follows as a natural course if you've received
366responses from queries to applet maintainer or positive responses from folks
367on the mailing list.
368
369We've made strident efforts to put a useful "collaboration" infrastructure in
370place in the form of mailing lists, the bug tracking system, and CVS. Please
371use these resources.
372
373
374Send Patches to the Bug Tracking System
375~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
376
377This was mentioned above in the "Making Sure Your Patch Doesn't Get Lost"
378section, but it is worth mentioning again. A patch sent to the mailing list
379might be unnoticed and forgotten. A patch sent to the bug tracking system will
380be stored and closely connected to the bug it fixes.
381
382
383Be Polite
384~~~~~~~~~
385
386The old saying "You'll catch more flies with honey than you will with vinegar"
387applies when submitting patches to the mailing list for approval. The way you
388present 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
390convince them that your patch should be included; it will likely have the
391opposite effect.
392
393
394
395Committing Changes to CVS
396-------------------------
397
398If you submit several patches that demonstrate that you are a skilled and wise
399coder, you may be invited to become a committer, thus enabling you to commit
400changes directly to CVS. This is nice because you don't have to wait for
401someone else to commit your change for you, you can just do it yourself.
402
403But note that this is a privilege that comes with some responsibilities. You
404should test your changes before you commit them. You should also talk to an
405applet maintainer before you make any kind of sweeping changes to somebody
406else's code. Big changes should still go to the mailing list first. Remember,
407being wise, polite, and discreet is more important than being clever.
408
409
410When To Commit
411~~~~~~~~~~~~~~
412
413Generally, 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
420The more of the above are true, the better it is to just commit a change
421directly to CVS.
422
423
424When Not To Commit
425~~~~~~~~~~~~~~~~~~
426
427Even if you have commit rights, you should probably still post a patch to the
428mailing 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
435The more of the above are true, the better it is to post a patch to the
436mailing list instead of committing.
437
438
439
440Final Words
441-----------
442
443If all of this seems complicated, don't panic, it's really not that tough. If
444you're having difficulty following some of the steps outlined in this
445document don't worry, the folks on the Busybox mailing list are a fairly
446good-natured bunch and will work with you to help get your patches into shape
447or help you make contributions.
448
449
Note: See TracBrowser for help on using the repository browser.