/[magellan-source]/trunk/mkinitrd-magellan/busybox/docs/contributing.txt

Contents of /trunk/mkinitrd-magellan/busybox/docs/contributing.txt

Revision 984 - (show annotations) (download)
Sun May 30 11:32:42 2010 UTC (13 years, 11 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