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
+The Busybox home page is at: http://busybox.net/
you need to do:
-Checkout the Latest Code from CVS
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Checkout the Latest Code
+~~~~~~~~~~~~~~~~~~~~~~~~
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 fixed
the bug you found. Somebody might have even added the feature you had in mind.
Don't make your work obsolete before you start!
-For information on how to check out Busybox from CVS, please look at the
+For information on how to check out Busybox development tree, please look at the
following links:
- http://oss.lineo.com/cvs_anon.html
- http://oss.lineo.com/cvs_howto.html
+ http://busybox.net/source.html
Read the Mailing List
Archives can be found here:
- http://opensource.lineo.com/lists/busybox/
+ http://busybox.net/lists/busybox/
-If you have a serious interest in Busybox, i.e. you are using it day-to-day or
+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 would be 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
+ http://busybox.net/mailman/listinfo/busybox
Coordinate with the Applet Maintainer
------------------------
Busybox can always use improvement! If you're looking for ways to help, there
-there are a variety of areas where you could help.
+are a variety of areas where you could help.
What Busybox Doesn't Need
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.
+ the upstream version. Rationale: bugs in these tools can destroy
+ vast amounts of data. Keeping up with filesystem format development
+ is impractical (especially in the area of keeping fsck tool safe
+ and up-to-date).
- 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.
independent. Do not send us tools that cannot be used across multiple
platforms / arches.
- - Any daemons that are not essential to basic system operation. To date, only
- syslogd and klogd meet this requirement. We do not need a web server, an
- ftp daemon, a dhcp server, a mail transport agent or a dns resolver. If you
- need one of those, you are welcome to ask the folks on the mailing list for
- recommendations, but please don't bloat up Busybox with any of these.
-
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:
+If you find bugs, please submit a detailed bug report to the busybox mailing
+list at busybox@busybox.net. A well-written bug report should include a
+transcript of a shell session that demonstrates the bad behavior and enables
+anyone else to duplicate the bug on their own machine. The following is such
+an example:
- http://bugs.lineo.com/Reporting.html
-
-The README file that comes with Busybox also describes how to submit a bug.
+ To: busybox@busybox.net
+ From: diligent@testing.linux.org
+ Subject: /bin/date doesn't work
-A well-written bug report should include a transcript of a shell session that
-demonstrates the bad behavior and enables anyone else to duplicate the bug on
-their own machine. The following is such an example:
+ Package: busybox
+ Version: 1.00
- When I execute Busybox 'date' it produces unexpected results.
+ When I execute Busybox 'date' it produces unexpected results.
+ With GNU date I get the following output:
- This is using GNU date:
$ date
Wed Mar 21 14:19:41 MST 2001
- This is using Busybox date:
- $ date
- codswaddle
-
+ But when I use BusyBox date I get this instead:
-Bug Triage
-~~~~~~~~~~
+ $ date
+ Illegal instruction
-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.
+ I am using Debian unstable, kernel version 2.4.19-rmk1 on an Netwinder,
+ and the latest uClibc from CVS.
-To see a listing of all the bugs currently filed against Busybox, look here:
+ -Diligent
- http://bugs.lineo.com/db/pa/lbusybox.html
+Note the careful description and use of examples showing not only what BusyBox
+does, but also a counter example showing what an equivalent GNU app does. Bug
+reports lacking such detail may never be fixed... Thanks for understanding.
-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
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
+ for i in TODO FIXME XXX; do find -name '*.[ch]'|xargs grep $i; 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
~~~~~~~~~~~~~~~~
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
+ http://www.securityfocus.com/popups/forums/secprog/intro.shtml
- 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
+ - C library function 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.
- "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
+ http://www.lysator.liu.se/c/ten-commandments.html
Other useful links:
- - the comp.lang.c FAQ: http://web.onetelnet.ch/~twolf/tw/c/index.html#Sources
+ - the comp.lang.c FAQ: http://home.datacomm.ch/t_wolf/tw/c/index.html#Sources
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'.
+If you've got anonymous Git access set up, making a patch is simple. Just make
+sure you're in the busybox/ directory and type:
+
+ git diff -b -w > 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
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.
+typing:
+
+ patch -p1 < 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,
~~~~~~~~~~~~~~~~~~
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
+to the mailing list, and especially before you push a change to Git. 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
+ 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
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:
+If you don't want your patch to be lost or forgotten, send it to the busybox
+mailing list 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)
+ Version: v1.01pre (or whatever the current version is)
Severity: wishlist
The remainder of the body should read along these lines:
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
-
-If you have a patch that will fix and close a reported bug, please send a
-message to [bugnumber]@bugs.lineo.com with your patch attached. It will catch
-people's attention if you have a subject line like the following:
-
- [PATCH INCLUDED] - Fix attached, please apply and close this bug
-
Improving Your Chances of Patch Acceptance
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
+place in the form of mailing lists, the bug tracking system, and Git. Please
use these resources.
-Committing Changes to CVS
--------------------------
+Pushing Changes to Git
+----------------------
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. This is nice because you don't have to wait for
-someone else to commit your change for you, you can just do it yourself.
+coder, you may be invited to become a committer, thus enabling you to push
+changes directly to Git. This is nice because you don't have to wait for
+someone else to push your change for you, you can just do it yourself.
-But note that this is a priviledge that comes with some responsibilities. You
-should test your changes before you commit them. You should also talk to an
+But note that this is a privilege that comes with some responsibilities. You
+should test your changes before you push them. You should also talk to an
applet maintainer before you make any kind of sweeping changes to somebody
else's code. Big changes should still go to the mailing list first. Remember,
being wise, polite, and discreet is more important than being clever.
+For more information on Git push access, see:
+
+ http://busybox.net/developer.html
-When To Commit
-~~~~~~~~~~~~~~
-Generally, you should feel free to commit a change if:
+When To Push
+~~~~~~~~~~~~
+
+Generally, you should feel free to push a change if:
- Your changes are small and don't touch many files
- You are fixing a bug
- Somebody has told you that it's okay
- It's obviously the Right Thing
-The more of the above are true, the better it is to just commit a change
-directly to CVS.
+The more of the above are true, the better it is to just push a change
+directly to Git.
-When Not To Commit
-~~~~~~~~~~~~~~~~~~
+When Not To Push
+~~~~~~~~~~~~~~~~
-Even if you have commit rights, you should probably still post a patch to the
+Even if you have push access, you should probably still post a patch to the
mailing list if:
- Your changes are broad and touch many different files
- You are adding a feature
- - Your changes are speculative or experimental (i.e. trying a new algorithm)
+ - Your changes are speculative or experimental (i.e., trying a new algorithm)
- You are not the maintainer and your changes make the maintainer cringe
The more of the above are true, the better it is to post a patch to the
-mailing list instead of committing.
+mailing list instead of pushing.
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.
-
-
projects / oweals / busybox.git / blobdiff