docs/contributing.txt - codeaurora/busybox - Gitiles

 Contributing To Busybox
 =======================

 This document describes what you need to do to contribute to Busybox, where
 you can help, guidelines on testing, and how to submit a well-formed patch
 that is more likely to be accepted.

 The Busybox home page is at: http://busybox.lineo.com


 Pre-Contribution Checklist
 --------------------------

 So you want to contribute to Busybox, eh? Great, wonderful, glad you want to
 help. However, before you dive in, headlong and hotfoot, there are some things
 you need to do:


 Checkout the Latest Code from CVS
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 This is a necessary first step. Please do not try to work with the last
 released version, as there is a good chance that somebody has already worked
 on the area you had in mind and your patch might already be obsolete.

 For information on how to check out Busybox from CVS, please look at the
 following links:

 	http://oss.lineo.com/cvs_anon.html
 	http://oss.lineo.com/cvs_howto.html


 Read the Mailing List
 ~~~~~~~~~~~~~~~~~~~~~

 No one is required to read the entire archives of the mailing list, but you
 should at least read up on what people have been talking about lately. If
 you've recently discovered a problem, chances are somebody else has too. If
 you're the first to discover a problem, post a message and let the rest of us
 know.

 Archives can be found here:

 	http://opensource.lineo.com/lists/busybox/

 If you have a serious interest in Busybox, i.e. you are using it day-to-day or
 as part of an embedded project, it's a good idea to join the mailing list.

 A web-based sign-up form can be found here:

 	http://opensource.lineo.com/mailman/listinfo/busybox


 Coordinate with the Applet Maintainer
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 Some (not all) of the applets in Busybox are "owned" by a maintainer who has
 put significant effort into it and is probably more familiar with it than
 others. To find the maintainer of an applet, look at the top of the .c file
 for a name following the word 'Copyright' or 'Written by'.

 Before plunging ahead, it's a good idea to send a message to the mailing list
 that says: "Hey, I was thinking about adding the 'transmogrify' feature to the
 'foo' applet.  Would this be useful? Is anyone else working on it?" You might
 want to CC the maintainer (if any) with your question.


 Areas Where You Can Help
 ------------------------

 Busybox can always use improvement! If you're looking for ways to help, there
 there are a variety of areas where you could help.


 What Busybox Doesn't Need
 ~~~~~~~~~~~~~~~~~~~~~~~~~

 Before listing the areas where you _can_ help, it's worthwhile to mention the
 areas where you shouldn't bother. While Busybox strives to be the "Swiss Army
 Knife" of embedded Linux, there are some applets that will not be accepted:

  - Any filesystem manipulation tools: Busybox is filesystem independent and
    we do not want to start adding mkfs/fsck tools for every (or any)
    filesystem under the sun. (fsck_minix.c and mkfs_minix.c are living on
    borrowed time.)  There are far too many of these tools out there.  Use
    the upstream version.  Not everything has to be part of Busybox.

  - Any partitioning tools: Partitioning a device is typically done once and
    only once, and tools which do this generally do not need to reside on the
    target device (esp a flash device). If you need a partitioning tool, grab
    one (such as fdisk, sfdisk, or cfdisk from util-linux) and use that, but
    don't try to merge it into busybox. These are nasty and complex and we
    don't want to maintain them.

  - Any disk, device, or media-specific tools: Use the -utils or -tools package
    that was designed for your device; don't try to shoehorn them into Busybox.

  - Any architecture specific tools: Busybox is (or should be) architecture
    independent. Do not send us tools that cannot be used across multiple
    platforms / arches.


 Bug Reporting
 ~~~~~~~~~~~~~

 If you find a bug in Busybox, you can send a bug report to our bug tracking
 system (homepage: http://bugs.lineo.com). Instructions on how to send a bug
 report to the tracking system can be found at:

 	http://bugs.lineo.com/Reporting.html

 The README file that comes with Busybox also describes how to submit a bug.

 A well-written bug report will include a transcript of a shell session that
 demonstrates the bad behavior and enables anyone else to duplicate the bug on
 their own machine.


 Bug Triage
 ~~~~~~~~~~

 Validating and confirming bugs is nearly as important as reporting them in the
 first place. It is valuable to know if a bug can be duplicated on a different
 machine, on a different filesystem, on a different architecture, with a
 different C library, and so forth.

 To see a listing of all the bugs currently filed against Busybox, look here:

 	http://bugs.lineo.com/db/pa/lbusybox.html

 If you have comments to add to a bug (can / can't duplicate, think a bug
 should be closed / reopened), please send it to [bugnumber]@bugs.lineo.com.
 The message you send will automatically be forwarded to the mailing list for
 all to see.


 Write Documentation
 ~~~~~~~~~~~~~~~~~~~

 Chances are, documentation in Busybox is either missing or needs improvement.
 Either way, help is welcome.

 Work is being done to automatically generate documentation from sources,
 especially from the usage.h file. If you want to correct the documentation,
 please make changes to the pre-generation parts, rather than the generated
 documentation. [More to come on this later...]

 It is preferred that modifications to documentation be submitted in patch
 format (more on this below), but we're a little more lenient when it comes to
 docs. You could, for example, just say "after the listing of the mount
 options, the following example would be helpful..."


 Consult Existing Sources
 ~~~~~~~~~~~~~~~~~~~~~~~~

 For a quick listing of "needs work" spots in the sources, cd into the Busybox
 directory and run the following:

 	for i in TODO FIXME XXX; do grep $i *.[ch]; done

 This will show all of the trouble spots or 'questionable' code. Pick a spot,
 any spot, these are all invitations for you to contribute.


 Consult The Bug-Tracking System
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 Head to: http://bugs.lineo.com/db/pa/lBusybox.html and look at the bugs on
 there. Pick one you think you can fix, and fix it. If it's a wishlist item and
 someone's requesting a new feature, take a stab at adding it. Everything
 previously said about "reading the mailing list" and "coordinating with the
 applet maintainer" still applies.


 Add a New Applet
 ~~~~~~~~~~~~~~~~

 If you want to add a new applet to Busybox, we'd love to see it. However,
 before you write any code, please ask beforehand on the mailing list something
 like "Do you think applet 'foo' would be useful in Busybox?" or "Would you
 guys accept applet 'foo' into Busybox if I were to write it?" If the answer is
 "no" by the folks on the mailing list, then you've saved yourself some time.
 Conversely, you could get some positive responses from folks who might be
 interested in helping you implement it, or can recommend the best approach.
 Perhaps most importantly, this is your way of calling "dibs" on something and
 avoiding duplication of effort.

 Also, before you write a line of code, please read the 'new-applet-HOWTO.txt'
 file in the docs/ directory.


 Janitorial Work
 ~~~~~~~~~~~~~~~

 These are dirty jobs, but somebody's gotta do 'em.

  - Converting applets to use getopt() for option processing. Type 'grep -L
    getopt *.c' to get a listing of the applets that currently don't use
    getopt. If a .c file processes no options, it should have a line that
    reads: /* no options, no getopt */ somewhere in the file.

  - Replace any "naked" calls to malloc, calloc, realloc, str[n]dup, fopen with
    the x* equivalents found in utility.c.

  - Security audits:
    http://www.securityfocus.com/frames/?content=/forums/secprog/secure-programming.html

  - Synthetic code removal: http://www.perl.com/pub/2000/06/commify.html - This
    is very Perl-specific, but the advice given in here applies equally well to
    C.

  - C library funciton use audits: Verifying that functions are being used
    properly (called with the right args), replacing unsafe library functions
    with safer versions, making sure return codes are being checked, etc.

  - Where appropriate, replace preprocessor defined macros and values with
    compile-time equivalents.

  - Makefile improvements:
    http://www.canb.auug.org.au/~millerp/rmch/recu-make-cons-harm.html
    (I think the recursive problems are pretty much taken care of at this point, non?)

  - "Ten Commandments" compliance: (this is a "maybe", certainly not as
    important as any of the previous items.)
     http://web.onetelnet.ch/~twolf/tw/c/ten_commandments.html

 Other useful links:

  - the comp.lang.c FAQ: http://web.onetelnet.ch/~twolf/tw/c/index.html#Sources


 Submitting Patches To Busybox
 -----------------------------

 Here are some guidelines on how to submit a patch to Busybox.


 Making A Patch
 ~~~~~~~~~~~~~~

 If you've got anonymous CVS access set up, making a patch is simple. Just make
 sure you're in the busybox/ directory and type 'cvs diff -bwu > mychanges.patch'.
 You can send the resulting .patch file to the mailing list with a description
 of what it does. (But not before you test it! See the next section for some
 guidelines.) It is preferred that patches be sent as attachments, but it is
 not required.

 Also, feel free to help test other people's patches and reply to them with
 comments. You can apply a patch by saving it into your busybox/ directory and
 typing 'patch < mychanges.patch'. Then you can recompile, see if it runs, test
 if it works as advertised, and post your findings to the mailing list.

 NOTE: Please do not include extraneous or irrelevant changes in your patches.
 Please do not try to "bundle" two patches together into one. Make single,
 discreet changes on a per-patch basis. Sometimes you need to make a patch that
 touches code in many places, but these kind of patches are rare and should be
 coordinated with a maintainer.


 Testing Guidelines
 ~~~~~~~~~~~~~~~~~~

 It's considered good form to test your new feature before you submit a patch
 to the mailing list, and especially before you commit a change to CVS. Here
 are some guidelines on how to test your changes.

  - Always test Busybox applets against GNU counterparts and make sure the
    behavior / output is identical between the two.

  - Try several different permutations and combinations of the features you're
    adding (i.e. different combinations of command-line switches) and make sure
    they all work; make sure one feature does not interfere with another.

  - Make sure you test compiling against the source both with the feature
    turned on and turned off in Config.h and make sure Busybox compiles cleanly
    both ways.

  - Run the multibuild.pl script in the tests directory and make sure
    everything checks out OK. (Do this from within the busybox/ directory by
    typing: 'tests/multibuild.pl'.)


 Making Sure Your Patch Doesn't Get Lost
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 If you don't want your patch to be lost or forgotten, send it to the bug
 tracking system (http://bugs.lineo.com). You do this by emailing your patch in
 a message to submit@bugs.lineo.com with a subject line something like this:

 	[PATCH] - Adds "transmogrify" feature to "foo"

 In the body, you should have a pseudo-header that looks like the following:

     Package: busybox
     Version: v0.50pre (or whatever the current version is)
     Severity: wishlist

 The remainder of the body should read along these lines:

 	This patch adds the "transmogrify" feature to the "foo" applet. I have
 	tested this on [arch] system(s) and it works. I have tested it against the
 	GNU counterparts and the outputs are identical. I have run the scripts in
 	the 'tests' directory and nothing breaks.

 Detailed instructions on how to submit a bug to the tracking system are at:

 	http://bugs.lineo.com/Reporting.html


 Improving Your Chances of Patch Acceptance
 ------------------------------------------

 Even after you send a brilliant patch to the mailing list, sometimes it can go
 unnoticed, un-replied-to, and sometimes (sigh) even lost. This is an
 unfortunate fact of life, but there are steps you can take to help your patch
 get noticed and convince a maintainer that it should be added:


 Be Succinct
 ~~~~~~~~~~~

 A patch that includes small, isolated, obvious changes is more likely to be
 accepted than a patch that touches code in lots of different places or makes
 sweeping, dubious changes.


 Back It Up
 ~~~~~~~~~~

 Hard facts on why your patch is better than the existing code will go a long
 way toward convincing maintainers that your patch should be included.
 Specifically, patches are more likely to be accepted if they are provably more
 correct, smaller, faster, simpler, or more maintainable than the existing
 code.

 Conversely, any patch that is supported with nothing more than "I think this
 would be cool" or "this patch is good because I say it is and I've got a Phd
 in Computer Science" will likely be ignored.


 Follow The Style Guide
 ~~~~~~~~~~~~~~~~~~~~~~

 It's considered good form to abide by the established coding style used in a
 project; Busybox is no exception. We have gone so far as to delineate the
 "elements of Busybox style" in the file docs/style-guide.txt. Please follow
 them.


 Work With Someone Else
 ~~~~~~~~~~~~~~~~~~~~~~

 Working on a patch in isolation is less effective than working with someone
 else for a variety of reasons. If another Busybox user is interested in what
 you're doing, then it's two (or more) voices instead of one that can petition
 for inclusion of the patch. You'll also have more people that can test your
 changes, or even offer suggestions on better approaches you could take.

 Getting other folks interested follows as a natural course if you've received
 responses from queries to applet maintainer or positive responses from folks
 on the mailing list.

 We've made strident efforts to put a useful "collaboration" infrastructure in
 place in the form of mailing lists, the bug tracking system, and CVS. Please
 use these resources.


 Be Polite
 ~~~~~~~~~

 The old saying "You'll catch more flies with honey than you will with vinegar"
 applies when submitting patches to the mailing list for approval. The way you
 present your patch is sometimes just as important as the actual patch itself
 (if not more so). Being rude to the maintainers is not an effective way to
 convince them that your patch should be included; it will likely have the
 opposite effect.


 Final Words
 -----------

 If all of this seems complicated, don't panic, it's really not that tough. If
 you're having difficulty following some of the steps outlined in this
 document don't worry, the folks on the Busybox mailing list are a fairly
 good-natured bunch and will work with you to help get your patches into shape
 or help you make contributions.

 If you submit several patches that demonstrate that you are a skilled and wise
 coder, you may be invited to become a committer, thus enabling you to commit
 changes directly to CVS.
	Contributing To Busybox
	=======================

	This document describes what you need to do to contribute to Busybox, where
	you can help, guidelines on testing, and how to submit a well-formed patch
	that is more likely to be accepted.

	The Busybox home page is at: http://busybox.lineo.com



	Pre-Contribution Checklist
	--------------------------

	So you want to contribute to Busybox, eh? Great, wonderful, glad you want to
	help. However, before you dive in, headlong and hotfoot, there are some things
	you need to do:


	Checkout the Latest Code from CVS
	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

	This is a necessary first step. Please do not try to work with the last
	released version, as there is a good chance that somebody has already worked
	on the area you had in mind and your patch might already be obsolete.

	For information on how to check out Busybox from CVS, please look at the
	following links:

	http://oss.lineo.com/cvs_anon.html
	http://oss.lineo.com/cvs_howto.html


	Read the Mailing List
	~~~~~~~~~~~~~~~~~~~~~

	No one is required to read the entire archives of the mailing list, but you
	should at least read up on what people have been talking about lately. If
	you've recently discovered a problem, chances are somebody else has too. If
	you're the first to discover a problem, post a message and let the rest of us
	know.

	Archives can be found here:

	http://opensource.lineo.com/lists/busybox/

	If you have a serious interest in Busybox, i.e. you are using it day-to-day or
	as part of an embedded project, it's a good idea to join the mailing list.

	A web-based sign-up form can be found here:

	http://opensource.lineo.com/mailman/listinfo/busybox


	Coordinate with the Applet Maintainer
	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

	Some (not all) of the applets in Busybox are "owned" by a maintainer who has
	put significant effort into it and is probably more familiar with it than
	others. To find the maintainer of an applet, look at the top of the .c file
	for a name following the word 'Copyright' or 'Written by'.

	Before plunging ahead, it's a good idea to send a message to the mailing list
	that says: "Hey, I was thinking about adding the 'transmogrify' feature to the
	'foo' applet. Would this be useful? Is anyone else working on it?" You might
	want to CC the maintainer (if any) with your question.



	Areas Where You Can Help
	------------------------

	Busybox can always use improvement! If you're looking for ways to help, there
	there are a variety of areas where you could help.


	What Busybox Doesn't Need
	~~~~~~~~~~~~~~~~~~~~~~~~~

	Before listing the areas where you _can_ help, it's worthwhile to mention the
	areas where you shouldn't bother. While Busybox strives to be the "Swiss Army
	Knife" of embedded Linux, there are some applets that will not be accepted:

	- Any filesystem manipulation tools: Busybox is filesystem independent and
	we do not want to start adding mkfs/fsck tools for every (or any)
	filesystem under the sun. (fsck_minix.c and mkfs_minix.c are living on
	borrowed time.) There are far too many of these tools out there. Use
	the upstream version. Not everything has to be part of Busybox.

	- Any partitioning tools: Partitioning a device is typically done once and
	only once, and tools which do this generally do not need to reside on the
	target device (esp a flash device). If you need a partitioning tool, grab
	one (such as fdisk, sfdisk, or cfdisk from util-linux) and use that, but
	don't try to merge it into busybox. These are nasty and complex and we
	don't want to maintain them.

	- Any disk, device, or media-specific tools: Use the -utils or -tools package
	that was designed for your device; don't try to shoehorn them into Busybox.

	- Any architecture specific tools: Busybox is (or should be) architecture
	independent. Do not send us tools that cannot be used across multiple
	platforms / arches.


	Bug Reporting
	~~~~~~~~~~~~~

	If you find a bug in Busybox, you can send a bug report to our bug tracking
	system (homepage: http://bugs.lineo.com). Instructions on how to send a bug
	report to the tracking system can be found at:

	http://bugs.lineo.com/Reporting.html

	The README file that comes with Busybox also describes how to submit a bug.

	A well-written bug report will include a transcript of a shell session that
	demonstrates the bad behavior and enables anyone else to duplicate the bug on
	their own machine.


	Bug Triage
	~~~~~~~~~~

	Validating and confirming bugs is nearly as important as reporting them in the
	first place. It is valuable to know if a bug can be duplicated on a different
	machine, on a different filesystem, on a different architecture, with a
	different C library, and so forth.

	To see a listing of all the bugs currently filed against Busybox, look here:

	http://bugs.lineo.com/db/pa/lbusybox.html

	If you have comments to add to a bug (can / can't duplicate, think a bug
	should be closed / reopened), please send it to [bugnumber]@bugs.lineo.com.
	The message you send will automatically be forwarded to the mailing list for
	all to see.


	Write Documentation
	~~~~~~~~~~~~~~~~~~~

	Chances are, documentation in Busybox is either missing or needs improvement.
	Either way, help is welcome.

	Work is being done to automatically generate documentation from sources,
	especially from the usage.h file. If you want to correct the documentation,
	please make changes to the pre-generation parts, rather than the generated
	documentation. [More to come on this later...]

	It is preferred that modifications to documentation be submitted in patch
	format (more on this below), but we're a little more lenient when it comes to
	docs. You could, for example, just say "after the listing of the mount
	options, the following example would be helpful..."


	Consult Existing Sources
	~~~~~~~~~~~~~~~~~~~~~~~~

	For a quick listing of "needs work" spots in the sources, cd into the Busybox
	directory and run the following:

	for i in TODO FIXME XXX; do grep $i *.[ch]; done

	This will show all of the trouble spots or 'questionable' code. Pick a spot,
	any spot, these are all invitations for you to contribute.


	Consult The Bug-Tracking System
	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

	Head to: http://bugs.lineo.com/db/pa/lBusybox.html and look at the bugs on
	there. Pick one you think you can fix, and fix it. If it's a wishlist item and
	someone's requesting a new feature, take a stab at adding it. Everything
	previously said about "reading the mailing list" and "coordinating with the
	applet maintainer" still applies.


	Add a New Applet
	~~~~~~~~~~~~~~~~

	If you want to add a new applet to Busybox, we'd love to see it. However,
	before you write any code, please ask beforehand on the mailing list something
	like "Do you think applet 'foo' would be useful in Busybox?" or "Would you
	guys accept applet 'foo' into Busybox if I were to write it?" If the answer is
	"no" by the folks on the mailing list, then you've saved yourself some time.
	Conversely, you could get some positive responses from folks who might be
	interested in helping you implement it, or can recommend the best approach.
	Perhaps most importantly, this is your way of calling "dibs" on something and
	avoiding duplication of effort.

	Also, before you write a line of code, please read the 'new-applet-HOWTO.txt'
	file in the docs/ directory.


	Janitorial Work
	~~~~~~~~~~~~~~~

	These are dirty jobs, but somebody's gotta do 'em.

	- Converting applets to use getopt() for option processing. Type 'grep -L
	getopt *.c' to get a listing of the applets that currently don't use
	getopt. If a .c file processes no options, it should have a line that
	reads: /* no options, no getopt */ somewhere in the file.

	- Replace any "naked" calls to malloc, calloc, realloc, str[n]dup, fopen with
	the x* equivalents found in utility.c.

	- Security audits:
	http://www.securityfocus.com/frames/?content=/forums/secprog/secure-programming.html

	- Synthetic code removal: http://www.perl.com/pub/2000/06/commify.html - This
	is very Perl-specific, but the advice given in here applies equally well to
	C.

	- C library funciton use audits: Verifying that functions are being used
	properly (called with the right args), replacing unsafe library functions
	with safer versions, making sure return codes are being checked, etc.

	- Where appropriate, replace preprocessor defined macros and values with
	compile-time equivalents.

	- Makefile improvements:
	http://www.canb.auug.org.au/~millerp/rmch/recu-make-cons-harm.html
	(I think the recursive problems are pretty much taken care of at this point, non?)

	- "Ten Commandments" compliance: (this is a "maybe", certainly not as
	important as any of the previous items.)
	http://web.onetelnet.ch/~twolf/tw/c/ten_commandments.html

	Other useful links:

	- the comp.lang.c FAQ: http://web.onetelnet.ch/~twolf/tw/c/index.html#Sources



	Submitting Patches To Busybox
	-----------------------------

	Here are some guidelines on how to submit a patch to Busybox.


	Making A Patch
	~~~~~~~~~~~~~~

	If you've got anonymous CVS access set up, making a patch is simple. Just make
	sure you're in the busybox/ directory and type 'cvs diff -bwu > mychanges.patch'.
	You can send the resulting .patch file to the mailing list with a description
	of what it does. (But not before you test it! See the next section for some
	guidelines.) It is preferred that patches be sent as attachments, but it is
	not required.

	Also, feel free to help test other people's patches and reply to them with
	comments. You can apply a patch by saving it into your busybox/ directory and
	typing 'patch < mychanges.patch'. Then you can recompile, see if it runs, test
	if it works as advertised, and post your findings to the mailing list.

	NOTE: Please do not include extraneous or irrelevant changes in your patches.
	Please do not try to "bundle" two patches together into one. Make single,
	discreet changes on a per-patch basis. Sometimes you need to make a patch that
	touches code in many places, but these kind of patches are rare and should be
	coordinated with a maintainer.


	Testing Guidelines
	~~~~~~~~~~~~~~~~~~

	It's considered good form to test your new feature before you submit a patch
	to the mailing list, and especially before you commit a change to CVS. Here
	are some guidelines on how to test your changes.

	- Always test Busybox applets against GNU counterparts and make sure the
	behavior / output is identical between the two.

	- Try several different permutations and combinations of the features you're
	adding (i.e. different combinations of command-line switches) and make sure
	they all work; make sure one feature does not interfere with another.

	- Make sure you test compiling against the source both with the feature
	turned on and turned off in Config.h and make sure Busybox compiles cleanly
	both ways.

	- Run the multibuild.pl script in the tests directory and make sure
	everything checks out OK. (Do this from within the busybox/ directory by
	typing: 'tests/multibuild.pl'.)


	Making Sure Your Patch Doesn't Get Lost
	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

	If you don't want your patch to be lost or forgotten, send it to the bug
	tracking system (http://bugs.lineo.com). You do this by emailing your patch in
	a message to submit@bugs.lineo.com with a subject line something like this:

	[PATCH] - Adds "transmogrify" feature to "foo"

	In the body, you should have a pseudo-header that looks like the following:

	Package: busybox
	Version: v0.50pre (or whatever the current version is)
	Severity: wishlist

	The remainder of the body should read along these lines:

	This patch adds the "transmogrify" feature to the "foo" applet. I have
	tested this on [arch] system(s) and it works. I have tested it against the
	GNU counterparts and the outputs are identical. I have run the scripts in
	the 'tests' directory and nothing breaks.

	Detailed instructions on how to submit a bug to the tracking system are at:

	http://bugs.lineo.com/Reporting.html



	Improving Your Chances of Patch Acceptance
	------------------------------------------

	Even after you send a brilliant patch to the mailing list, sometimes it can go
	unnoticed, un-replied-to, and sometimes (sigh) even lost. This is an
	unfortunate fact of life, but there are steps you can take to help your patch
	get noticed and convince a maintainer that it should be added:


	Be Succinct
	~~~~~~~~~~~

	A patch that includes small, isolated, obvious changes is more likely to be
	accepted than a patch that touches code in lots of different places or makes
	sweeping, dubious changes.


	Back It Up
	~~~~~~~~~~

	Hard facts on why your patch is better than the existing code will go a long
	way toward convincing maintainers that your patch should be included.
	Specifically, patches are more likely to be accepted if they are provably more
	correct, smaller, faster, simpler, or more maintainable than the existing
	code.

	Conversely, any patch that is supported with nothing more than "I think this
	would be cool" or "this patch is good because I say it is and I've got a Phd
	in Computer Science" will likely be ignored.


	Follow The Style Guide
	~~~~~~~~~~~~~~~~~~~~~~

	It's considered good form to abide by the established coding style used in a
	project; Busybox is no exception. We have gone so far as to delineate the
	"elements of Busybox style" in the file docs/style-guide.txt. Please follow
	them.


	Work With Someone Else
	~~~~~~~~~~~~~~~~~~~~~~

	Working on a patch in isolation is less effective than working with someone
	else for a variety of reasons. If another Busybox user is interested in what
	you're doing, then it's two (or more) voices instead of one that can petition
	for inclusion of the patch. You'll also have more people that can test your
	changes, or even offer suggestions on better approaches you could take.

	Getting other folks interested follows as a natural course if you've received
	responses from queries to applet maintainer or positive responses from folks
	on the mailing list.

	We've made strident efforts to put a useful "collaboration" infrastructure in
	place in the form of mailing lists, the bug tracking system, and CVS. Please
	use these resources.


	Be Polite
	~~~~~~~~~

	The old saying "You'll catch more flies with honey than you will with vinegar"
	applies when submitting patches to the mailing list for approval. The way you
	present your patch is sometimes just as important as the actual patch itself
	(if not more so). Being rude to the maintainers is not an effective way to
	convince them that your patch should be included; it will likely have the
	opposite effect.



	Final Words
	-----------

	If all of this seems complicated, don't panic, it's really not that tough. If
	you're having difficulty following some of the steps outlined in this
	document don't worry, the folks on the Busybox mailing list are a fairly
	good-natured bunch and will work with you to help get your patches into shape
	or help you make contributions.

	If you submit several patches that demonstrate that you are a skilled and wise
	coder, you may be invited to become a committer, thus enabling you to commit
	changes directly to CVS.