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

Last change on this file since 3320 was 3320, checked in by Bruno Cornec, 6 years ago
  • Re-add (thanks git BTW) the 2.2.9 branch which had been destroyed in the move to 3.0
  • Property svn:eol-style set to native
File size: 15.3 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
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 development tree, please look at the
29following links:
30
31    http://busybox.net/source.html
32
33
34Read the Mailing List
35~~~~~~~~~~~~~~~~~~~~~
36
37No one is required to read the entire archives of the mailing list, but you
38should at least read up on what people have been talking about lately. If
39you've recently discovered a problem, chances are somebody else has too. If
40you're the first to discover a problem, post a message and let the rest of us
41know.
42
43Archives can be found here:
44
45    http://busybox.net/lists/busybox/
46
47If you have a serious interest in Busybox, i.e., you are using it day-to-day or
48as part of an embedded project, it would be a good idea to join the mailing
49list.
50
51A web-based sign-up form can be found here:
52
53    http://busybox.net/mailman/listinfo/busybox
54
55
56Coordinate with the Applet Maintainer
57~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
58
59Some (not all) of the applets in Busybox are "owned" by a maintainer who has
60put significant effort into it and is probably more familiar with it than
61others. To find the maintainer of an applet, look at the top of the .c file
62for a name following the word 'Copyright' or 'Written by' or 'Maintainer'.
63
64Before plunging ahead, it's a good idea to send a message to the mailing list
65that 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
67want to CC the maintainer (if any) with your question.
68
69
70
71Areas Where You Can Help
72------------------------
73
74Busybox can always use improvement! If you're looking for ways to help, there
75are a variety of areas where you could help.
76
77
78What Busybox Doesn't Need
79~~~~~~~~~~~~~~~~~~~~~~~~~
80
81Before listing the areas where you _can_ help, it's worthwhile to mention the
82areas where you shouldn't bother. While Busybox strives to be the "Swiss Army
83Knife" 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
102Bug Reporting
103~~~~~~~~~~~~~
104
105If you find bugs, please submit a detailed bug report to the busybox mailing
106list at busybox@busybox.net.  A well-written bug report should include a
107transcript of a shell session that demonstrates the bad behavior and enables
108anyone else to duplicate the bug on their own machine. The following is such
109an 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
134Note the careful description and use of examples showing not only what BusyBox
135does, but also a counter example showing what an equivalent GNU app does.  Bug
136reports lacking such detail may never be fixed...  Thanks for understanding.
137
138
139
140Write Documentation
141~~~~~~~~~~~~~~~~~~~
142
143Chances are, documentation in Busybox is either missing or needs improvement.
144Either way, help is welcome.
145
146Work is being done to automatically generate documentation from sources,
147especially from the usage.h file. If you want to correct the documentation,
148please make changes to the pre-generation parts, rather than the generated
149documentation. [More to come on this later...]
150
151It is preferred that modifications to documentation be submitted in patch
152format (more on this below), but we're a little more lenient when it comes to
153docs. You could, for example, just say "after the listing of the mount
154options, the following example would be helpful..."
155
156
157Consult Existing Sources
158~~~~~~~~~~~~~~~~~~~~~~~~
159
160For a quick listing of "needs work" spots in the sources, cd into the Busybox
161directory and run the following:
162
163    for i in TODO FIXME XXX; do find -name '*.[ch]'|xargs grep $i; done
164
165This will show all of the trouble spots or 'questionable' code. Pick a spot,
166any spot, these are all invitations for you to contribute.
167
168
169Add a New Applet
170~~~~~~~~~~~~~~~~
171
172If you want to add a new applet to Busybox, we'd love to see it. However,
173before you write any code, please ask beforehand on the mailing list something
174like "Do you think applet 'foo' would be useful in Busybox?" or "Would you
175guys 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.
177Conversely, you could get some positive responses from folks who might be
178interested in helping you implement it, or can recommend the best approach.
179Perhaps most importantly, this is your way of calling "dibs" on something and
180avoiding duplication of effort.
181
182Also, before you write a line of code, please read the 'new-applet-HOWTO.txt'
183file in the docs/ directory.
184
185
186Janitorial Work
187~~~~~~~~~~~~~~~
188
189These 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
217Other useful links:
218
219 - the comp.lang.c FAQ: http://home.datacomm.ch/t_wolf/tw/c/index.html#Sources
220
221
222
223Submitting Patches To Busybox
224-----------------------------
225
226Here are some guidelines on how to submit a patch to Busybox.
227
228
229Making A Patch
230~~~~~~~~~~~~~~
231
232If you've got anonymous Git access set up, making a patch is simple. Just make
233sure you're in the busybox/ directory and type:
234
235    git diff -b -w > mychanges.patch
236
237You can send the resulting .patch file to the mailing list with a description
238of what it does. (But not before you test it! See the next section for some
239guidelines.) It is preferred that patches be sent as attachments, but it is
240not required.
241
242Also, feel free to help test other people's patches and reply to them with
243comments. You can apply a patch by saving it into your busybox/ directory and
244typing:
245
246    patch -p1 < mychanges.patch
247
248Then you can recompile, see if it runs, test if it works as advertised, and
249post your findings to the mailing list.
250
251NOTE: Please do not include extraneous or irrelevant changes in your patches.
252Please do not try to "bundle" two patches together into one. Make single,
253discreet changes on a per-patch basis. Sometimes you need to make a patch that
254touches code in many places, but these kind of patches are rare and should be
255coordinated with a maintainer.
256
257
258Testing Guidelines
259~~~~~~~~~~~~~~~~~~
260
261It's considered good form to test your new feature before you submit a patch
262to the mailing list, and especially before you push a change to Git. Here
263are some guidelines on how to test your changes.
264
265 - Always test Busybox applets against GNU counterparts and make sure the
266   behavior / output is identical between the two.
267
268 - Try several different permutations and combinations of the features you're
269   adding (i.e., different combinations of command-line switches) and make sure
270   they all work; make sure one feature does not interfere with another.
271
272 - Make sure you test compiling against the source both with the feature
273   turned on and turned off in Config.h and make sure Busybox compiles cleanly
274   both ways.
275
276 - Run the multibuild.pl script in the tests directory and make sure
277   everything checks out OK. (Do this from within the busybox/ directory by
278   typing: 'tests/multibuild.pl'.)
279
280
281Making Sure Your Patch Doesn't Get Lost
282~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
283
284If you don't want your patch to be lost or forgotten, send it to the busybox
285mailing list with a subject line something like this:
286
287    [PATCH] - Adds "transmogrify" feature to "foo"
288
289In the body, you should have a pseudo-header that looks like the following:
290
291    Package: busybox
292    Version: v1.01pre (or whatever the current version is)
293    Severity: wishlist
294
295The remainder of the body should read along these lines:
296
297    This patch adds the "transmogrify" feature to the "foo" applet. I have
298    tested this on [arch] system(s) and it works. I have tested it against the
299    GNU counterparts and the outputs are identical. I have run the scripts in
300    the 'tests' directory and nothing breaks.
301
302
303
304Improving Your Chances of Patch Acceptance
305------------------------------------------
306
307Even after you send a brilliant patch to the mailing list, sometimes it can go
308unnoticed, un-replied-to, and sometimes (sigh) even lost. This is an
309unfortunate fact of life, but there are steps you can take to help your patch
310get noticed and convince a maintainer that it should be added:
311
312
313Be Succinct
314~~~~~~~~~~~
315
316A patch that includes small, isolated, obvious changes is more likely to be
317accepted than a patch that touches code in lots of different places or makes
318sweeping, dubious changes.
319
320
321Back It Up
322~~~~~~~~~~
323
324Hard facts on why your patch is better than the existing code will go a long
325way toward convincing maintainers that your patch should be included.
326Specifically, patches are more likely to be accepted if they are provably more
327correct, smaller, faster, simpler, or more maintainable than the existing
328code.
329
330Conversely, any patch that is supported with nothing more than "I think this
331would be cool" or "this patch is good because I say it is and I've got a Phd
332in Computer Science" will likely be ignored.
333
334
335Follow The Style Guide
336~~~~~~~~~~~~~~~~~~~~~~
337
338It's considered good form to abide by the established coding style used in a
339project; Busybox is no exception. We have gone so far as to delineate the
340"elements of Busybox style" in the file docs/style-guide.txt. Please follow
341them.
342
343
344Work With Someone Else
345~~~~~~~~~~~~~~~~~~~~~~
346
347Working on a patch in isolation is less effective than working with someone
348else for a variety of reasons. If another Busybox user is interested in what
349you're doing, then it's two (or more) voices instead of one that can petition
350for inclusion of the patch. You'll also have more people that can test your
351changes, or even offer suggestions on better approaches you could take.
352
353Getting other folks interested follows as a natural course if you've received
354responses from queries to applet maintainer or positive responses from folks
355on the mailing list.
356
357We've made strident efforts to put a useful "collaboration" infrastructure in
358place in the form of mailing lists, the bug tracking system, and Git. Please
359use these resources.
360
361
362Send Patches to the Bug Tracking System
363~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
364
365This was mentioned above in the "Making Sure Your Patch Doesn't Get Lost"
366section, but it is worth mentioning again. A patch sent to the mailing list
367might be unnoticed and forgotten. A patch sent to the bug tracking system will
368be stored and closely connected to the bug it fixes.
369
370
371Be Polite
372~~~~~~~~~
373
374The old saying "You'll catch more flies with honey than you will with vinegar"
375applies when submitting patches to the mailing list for approval. The way you
376present your patch is sometimes just as important as the actual patch itself
377(if not more so). Being rude to the maintainers is not an effective way to
378convince them that your patch should be included; it will likely have the
379opposite effect.
380
381
382
383Pushing Changes to Git
384----------------------
385
386If you submit several patches that demonstrate that you are a skilled and wise
387coder, you may be invited to become a committer, thus enabling you to push
388changes directly to Git. This is nice because you don't have to wait for
389someone else to push your change for you, you can just do it yourself.
390
391But note that this is a privilege that comes with some responsibilities. You
392should test your changes before you push them. You should also talk to an
393applet maintainer before you make any kind of sweeping changes to somebody
394else's code. Big changes should still go to the mailing list first. Remember,
395being wise, polite, and discreet is more important than being clever.
396
397For more information on Git push access, see:
398
399    http://busybox.net/developer.html
400
401
402When To Push
403~~~~~~~~~~~~
404
405Generally, you should feel free to push a change if:
406
407 - Your changes are small and don't touch many files
408 - You are fixing a bug
409 - Somebody has told you that it's okay
410 - It's obviously the Right Thing
411
412The more of the above are true, the better it is to just push a change
413directly to Git.
414
415
416When Not To Push
417~~~~~~~~~~~~~~~~
418
419Even if you have push access, you should probably still post a patch to the
420mailing list if:
421
422 - Your changes are broad and touch many different files
423 - You are adding a feature
424 - Your changes are speculative or experimental (i.e., trying a new algorithm)
425 - You are not the maintainer and your changes make the maintainer cringe
426
427The more of the above are true, the better it is to post a patch to the
428mailing list instead of pushing.
429
430
431
432Final Words
433-----------
434
435If all of this seems complicated, don't panic, it's really not that tough. If
436you're having difficulty following some of the steps outlined in this
437document don't worry, the folks on the Busybox mailing list are a fairly
438good-natured bunch and will work with you to help get your patches into shape
439or help you make contributions.
Note: See TracBrowser for help on using the repository browser.