aboutsummaryrefslogtreecommitdiff
path: root/docs/contributing.txt
diff options
context:
space:
mode:
authorMark Whitley <markw@lineo.com>2001-03-02 19:14:25 +0000
committerMark Whitley <markw@lineo.com>2001-03-02 19:14:25 +0000
commit3b565cdf910a95e0955d3480fcd617fa5dbda78b (patch)
tree7c36bee48bb6dce655a4535311a928f3b22464d9 /docs/contributing.txt
parent85adecb668cec178d32775547ebde4eb4f1e9149 (diff)
downloadbusybox-w32-3b565cdf910a95e0955d3480fcd617fa5dbda78b.tar.gz
busybox-w32-3b565cdf910a95e0955d3480fcd617fa5dbda78b.tar.bz2
busybox-w32-3b565cdf910a95e0955d3480fcd617fa5dbda78b.zip
Added 'How to contribute to Busybox' doc.
Diffstat (limited to 'docs/contributing.txt')
-rw-r--r--docs/contributing.txt390
1 files changed, 390 insertions, 0 deletions
diff --git a/docs/contributing.txt b/docs/contributing.txt
new file mode 100644
index 000000000..696e63c2c
--- /dev/null
+++ b/docs/contributing.txt
@@ -0,0 +1,390 @@
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.lineo.com
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 worked
25on the area you had in mind and your patch might already be obsolete.
26
27For information on how to check out Busybox from CVS, please look at the
28following links:
29
30 http://oss.lineo.com/cvs_anon.html
31 http://oss.lineo.com/cvs_howto.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://opensource.lineo.com/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's a good idea to join the mailing list.
49
50A web-based sign-up form can be found here:
51
52 http://opensource.lineo.com/mailman/listinfo/busybox
53
54
55Coordinate with the Applet Maintainer
56~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
57
58Some (not all) of the applets in Busybox are "owned" by a maintainer who has
59put significant effort into it and is probably more familiar with it than
60others. To find the maintainer of an applet, look at the top of the .c file
61for a name following the word 'Copyright' or 'Written by'.
62
63Before plunging ahead, it's a good idea to send a message to the mailing list
64that says: "Hey, I was thinking about adding the 'transmogrify' feature to the
65'foo' applet. Would this be useful? Is anyone else working on it?" You might
66want to CC the maintainer (if any) with your question.
67
68
69
70Areas Where You Can Help
71------------------------
72
73Busybox can always use improvement! If you're looking for ways to help, there
74there are a variety of areas where you could help.
75
76
77What Busybox Doesn't Need
78~~~~~~~~~~~~~~~~~~~~~~~~~
79
80Before listing the areas where you _can_ help, it's worthwhile to mention the
81areas where you shouldn't bother. While Busybox strives to be the "Swiss Army
82Knife" of embedded Linux, there are some applets that will not be accepted:
83
84 - Any filesystem manipulation tools: Busybox is filesystem independent and
85 we do not want to start adding mkfs/fsck tools for every (or any)
86 filesystem under the sun. (fsck_minix.c and mkfs_minix.c are living on
87 borrowed time.) There are far too many of these tools out there. Use
88 the upstream version. Not everything has to be part of Busybox.
89
90 - Any partitioning tools: Partitioning a device is typically done once and
91 only once, and tools which do this generally do not need to reside on the
92 target device (esp a flash device). If you need a partitioning tool, grab
93 one (such as fdisk, sfdisk, or cfdisk from util-linux) and use that, but
94 don't try to merge it into busybox. These are nasty and complex and we
95 don't want to maintain them.
96
97 - Any disk, device, or media-specific tools: Use the -utils or -tools package
98 that was designed for your device; don't try to shoehorn them into Busybox.
99
100 - Any architecture specific tools: Busybox is (or should be) architecture
101 independent. Do not send us tools that cannot be used across multiple
102 platforms / arches.
103
104
105Bug Reporting
106~~~~~~~~~~~~~
107
108If you find a bug in Busybox, you can send a bug report to our bug tracking
109system (homepage: http://bugs.lineo.com). Instructions on how to send a bug
110report to the tracking system can be found at:
111
112 http://bugs.lineo.com/Reporting.html
113
114The README file that comes with Busybox also describes how to submit a bug.
115
116A well-written bug report will include a transcript of a shell session that
117demonstrates the bad behavior and enables anyone else to duplicate the bug on
118their own machine.
119
120
121Bug Triage
122~~~~~~~~~~
123
124Validating and confirming bugs is nearly as important as reporting them in the
125first place. It is valuable to know if a bug can be duplicated on a different
126machine, on a different filesystem, on a different architecture, with a
127different C library, and so forth.
128
129To see a listing of all the bugs currently filed against Busybox, look here:
130
131 http://bugs.lineo.com/db/pa/lbusybox.html
132
133If you have comments to add to a bug (can / can't duplicate, think a bug
134should be closed / reopened), please send it to [bugnumber]@bugs.lineo.com.
135The message you send will automatically be forwarded to the mailing list for
136all to see.
137
138
139Write Documentation
140~~~~~~~~~~~~~~~~~~~
141
142Chances are, documentation in Busybox is either missing or needs improvement.
143Either way, help is welcome.
144
145Work is being done to automatically generate documentation from sources,
146especially from the usage.h file. If you want to correct the documentation,
147please make changes to the pre-generation parts, rather than the generated
148documentation. [More to come on this later...]
149
150It is preferred that modifications to documentation be submitted in patch
151format (more on this below), but we're a little more lenient when it comes to
152docs. You could, for example, just say "after the listing of the mount
153options, the following example would be helpful..."
154
155
156Consult Existing Sources
157~~~~~~~~~~~~~~~~~~~~~~~~
158
159For a quick listing of "needs work" spots in the sources, cd into the Busybox
160directory and run the following:
161
162 for i in TODO FIXME XXX; do grep $i *.[ch]; done
163
164This will show all of the trouble spots or 'questionable' code. Pick a spot,
165any spot, these are all invitations for you to contribute.
166
167
168Consult The Bug-Tracking System
169~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
170
171Head to: http://bugs.lineo.com/db/pa/lBusybox.html and look at the bugs on
172there. Pick one you think you can fix, and fix it. If it's a wishlist item and
173someone's requesting a new feature, take a stab at adding it. Everything
174previously said about "reading the mailing list" and "coordinating with the
175applet maintainer" still applies.
176
177
178Add a New Applet
179~~~~~~~~~~~~~~~~
180
181If you want to add a new applet to Busybox, we'd love to see it. However,
182before you write any code, please ask beforehand on the mailing list something
183like "Do you think applet 'foo' would be useful in Busybox?" or "Would you
184guys accept applet 'foo' into Busybox if I were to write it?" If the answer is
185"no" by the folks on the mailing list, then you've saved yourself some time.
186Conversely, you could get some positive responses from folks who might be
187interested in helping you implement it, or can recommend the best approach.
188Perhaps most importantly, this is your way of calling "dibs" on something and
189avoiding duplication of effort.
190
191Also, before you write a line of code, please read the 'new-applet-HOWTO.txt'
192file in the docs/ directory.
193
194
195Janitorial Work
196~~~~~~~~~~~~~~~
197
198These are dirty jobs, but somebody's gotta do 'em.
199
200 - Security audits:
201 http://www.securityfocus.com/frames/?content=/forums/secprog/secure-programming.html
202
203 - Synthetic code removal: http://www.perl.com/pub/2000/06/commify.html - This
204 is very Perl-specific, but the advice given in here applies equally well to
205 C.
206
207 - C library funciton use audits: Verifying that functions are being used
208 properly (called with the right args), replacing unsafe library functions
209 with safer versions, making sure return codes are being checked, etc.
210
211 - Where appropriate, replace preprocessor defined macros and values with
212 compile-time equivalents.
213
214 - Makefile improvements:
215 http://www.canb.auug.org.au/~millerp/rmch/recu-make-cons-harm.html
216 (I think the recursive problems are pretty much taken care of at this point, non?)
217
218 - "Ten Commandments" compliance: (this is a "maybe", certainly not as
219 important as any of the previous items.)
220 http://web.onetelnet.ch/~twolf/tw/c/ten_commandments.html
221
222Other useful links:
223
224 - the comp.lang.c FAQ: http://web.onetelnet.ch/~twolf/tw/c/index.html#Sources
225
226
227
228Submitting Patches To Busybox
229-----------------------------
230
231Here are some guidelines on how to submit a patch to Busybox.
232
233
234Making A Patch
235~~~~~~~~~~~~~~
236
237If you've got anonymous CVS access set up, making a patch is simple. Just make
238sure you're in the busybox/ directory and type 'cvs diff -bwu > mychanges.patch'.
239You can send the resulting .patch file to the mailing list with a description
240of what it does. (But not before you test it! See the next section for some
241guidelines.) It is preferred that patches be sent as attachments, but it is
242not required.
243
244Also, feel free to help test other people's patches and reply to them with
245comments. You can apply a patch by saving it into your busybox/ directory and
246typing 'patch < mychanges.patch'. Then you can recompile, see if it runs, test
247if it works as advertised, and post your findings to the mailing list.
248
249NOTE: Please do not include extraneous or irrelevant changes in your patches.
250Please do not try to "bundle" two patches together into one. Make single,
251discreet changes on a per-patch basis. Sometimes you need to make a patch that
252touches code in many places, but these kind of patches are rare and should be
253coordinated with a maintainer.
254
255
256Testing Guidelines
257~~~~~~~~~~~~~~~~~~
258
259It's considered good form to test your new feature before you submit a patch
260to the mailing list, and especially before you commit a change to CVS. Here
261are some guidelines on how to test your changes.
262
263 - Always test Busybox applets against GNU counterparts and make sure the
264 behavior / output is identical between the two.
265
266 - Try several different permutations and combinations of the features you're
267 adding (i.e. different combinations of command-line switches) and make sure
268 they all work; make sure one feature does not interfere with another.
269
270 - Make sure you test compiling against the source both with the feature
271 turned on and turned off in Config.h and make sure Busybox compiles cleanly
272 both ways.
273
274 - Run the multibuild.pl script in the tests directory and make sure
275 everything checks out OK. (Do this from within the busybox/ directory by
276 typing: 'tests/multibuild.pl'.)
277
278
279Making Sure Your Patch Doesn't Get Lost
280~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
281
282If you don't want your patch to be lost or forgotten, send it to the bug
283tracking system (http://bugs.lineo.com). You do this by emailing your patch in
284a message to submit@bugs.lineo.com with a subject line something like this:
285
286 [PATCH] - Adds "transmogrify" feature to "foo"
287
288In the body, you should have a pseudo-header that looks like the following:
289
290 Package: busybox
291 Version: v0.50pre (or whatever the current version is)
292 Severity: wishlist
293
294The remainder of the body should read along these lines:
295
296 This patch adds the "transmogrify" feature to the "foo" applet. I have
297 tested this on [arch] system(s) and it works. I have tested it against the
298 GNU counterparts and the outputs are identical. I have run the scripts in
299 the 'tests' directory and nothing breaks.
300
301Detailed instructions on how to submit a bug to the tracking system are at:
302
303 http://bugs.lineo.com/Reporting.html
304
305
306
307Improving Your Chances of Patch Acceptance
308------------------------------------------
309
310Even after you send a brilliant patch to the mailing list, sometimes it can go
311unnoticed, un-replied-to, and sometimes (sigh) even lost. This is an
312unfortunate fact of life, but there are steps you can take to help your patch
313get noticed and convince a maintainer that it should be added:
314
315
316Be Succinct
317~~~~~~~~~~~
318
319A patch that includes small, isolated, obvious changes is more likely to be
320accepted than a patch that touches code in lots of different places or makes
321sweeping, dubious changes.
322
323
324Back It Up
325~~~~~~~~~~
326
327Hard facts on why your patch is better than the existing code will go a long
328way toward convincing maintainers that your patch should be included.
329Specifically, patches are more likely to be accepted if they are provably more
330correct, smaller, faster, simpler, or more maintainable than the existing
331code.
332
333Conversely, any patch that is supported with nothing more than "I think this
334would be cool" or "this patch is good because I say it is and I've got a Phd
335in Computer Science" will likely be ignored.
336
337
338Follow The Style Guide
339~~~~~~~~~~~~~~~~~~~~~~
340
341It's considered good form to abide by the established coding style used in a
342project; Busybox is no exception. We have gone so far as to delineate the
343"elements of Busybox style" in the file docs/style-guide.txt. Please follow
344them.
345
346
347Work With Someone Else
348~~~~~~~~~~~~~~~~~~~~~~
349
350Working on a patch in isolation is less effective than working with someone
351else for a variety of reasons. If another Busybox user is interested in what
352you're doing, then it's two (or more) voices instead of one that can petition
353for inclusion of the patch. You'll also have more people that can test your
354changes, or even offer suggestions on better approaches you could take.
355
356Getting other folks interested follows as a natural course if you've received
357responses from queries to applet maintainer or positive responses from folks
358on the mailing list.
359
360We've made strident efforts to put a useful "collaboration" infrastructure in
361place in the form of mailing lists, the bug tracking system, and CVS. Please
362use these resources.
363
364
365Be Polite
366~~~~~~~~~
367
368The old saying "You'll catch more flies with honey than you will with vinegar"
369applies when submitting patches to the mailing list for approval. The way you
370present your patch is sometimes just as important as the actual patch itself
371(if not more so). Being rude to the maintainers is not an effective way to
372convince them that your patch should be included; it will likely have the
373opposite effect.
374
375
376
377Final Words
378-----------
379
380If all of this seems complicated, don't panic, it's really not that tough. If
381you're having difficulty following some of the steps outlined in this
382document don't worry, the folks on the Busybox mailing list are a fairly
383good-natured bunch and will work with you to help get your patches into shape
384or help you make contributions.
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 commit
388changes directly to CVS.
389
390