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 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 from CVS, please look at the 29following links: 30 31 http://oss.lineo.com/cvs_anon.html 32 http://oss.lineo.com/cvs_howto.html 33 34 35Read the Mailing List 36~~~~~~~~~~~~~~~~~~~~~ 37 38No one is required to read the entire archives of the mailing list, but you 39should at least read up on what people have been talking about lately. If 40you've recently discovered a problem, chances are somebody else has too. If 41you're the first to discover a problem, post a message and let the rest of us 42know. 43 44Archives can be found here: 45 46 http://opensource.lineo.com/lists/busybox/ 47 48If you have a serious interest in Busybox, i.e., you are using it day-to-day or 49as part of an embedded project, it would be a good idea to join the mailing 50list. 51 52A web-based sign-up form can be found here: 53 54 http://opensource.lineo.com/mailman/listinfo/busybox 55 56 57Coordinate with the Applet Maintainer 58~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 59 60Some (not all) of the applets in Busybox are "owned" by a maintainer who has 61put significant effort into it and is probably more familiar with it than 62others. To find the maintainer of an applet, look at the top of the .c file 63for a name following the word 'Copyright' or 'Written by' or 'Maintainer'. 64 65Before plunging ahead, it's a good idea to send a message to the mailing list 66that says: "Hey, I was thinking about adding the 'transmogrify' feature to the 67'foo' applet. Would this be useful? Is anyone else working on it?" You might 68want to CC the maintainer (if any) with your question. 69 70 71 72Areas Where You Can Help 73------------------------ 74 75Busybox can always use improvement! If you're looking for ways to help, there 76there are a variety of areas where you could help. 77 78 79What Busybox Doesn't Need 80~~~~~~~~~~~~~~~~~~~~~~~~~ 81 82Before listing the areas where you _can_ help, it's worthwhile to mention the 83areas where you shouldn't bother. While Busybox strives to be the "Swiss Army 84Knife" of embedded Linux, there are some applets that will not be accepted: 85 86 - Any filesystem manipulation tools: Busybox is filesystem independent and 87 we do not want to start adding mkfs/fsck tools for every (or any) 88 filesystem under the sun. (fsck_minix.c and mkfs_minix.c are living on 89 borrowed time.) There are far too many of these tools out there. Use 90 the upstream version. Not everything has to be part of Busybox. 91 92 - Any partitioning tools: Partitioning a device is typically done once and 93 only once, and tools which do this generally do not need to reside on the 94 target device (esp a flash device). If you need a partitioning tool, grab 95 one (such as fdisk, sfdisk, or cfdisk from util-linux) and use that, but 96 don't try to merge it into busybox. These are nasty and complex and we 97 don't want to maintain them. 98 99 - Any disk, device, or media-specific tools: Use the -utils or -tools package 100 that was designed for your device; don't try to shoehorn them into Busybox. 101 102 - Any architecture specific tools: Busybox is (or should be) architecture 103 independent. Do not send us tools that cannot be used across multiple 104 platforms / arches. 105 106 - Any daemons that are not essential to basic system operation. To date, only 107 syslogd and klogd meet this requirement. We do not need a web server, an 108 ftp daemon, a dhcp server, a mail transport agent or a dns resolver. If you 109 need one of those, you are welcome to ask the folks on the mailing list for 110 recommendations, but please don't bloat up Busybox with any of these. 111 112 113Bug Reporting 114~~~~~~~~~~~~~ 115 116If you find a bug in Busybox, you can send a bug report to our bug tracking 117system (homepage: http://bugs.lineo.com). Instructions on how to send a bug 118report to the tracking system can be found at: 119 120 http://bugs.lineo.com/Reporting.html 121 122The README file that comes with Busybox also describes how to submit a bug. 123 124A well-written bug report should include a transcript of a shell session that 125demonstrates the bad behavior and enables anyone else to duplicate the bug on 126their own machine. The following is such an example: 127 128 When I execute Busybox 'date' it produces unexpected results. 129 130 This is using GNU date: 131 $ date 132 Wed Mar 21 14:19:41 MST 2001 133 134 This is using Busybox date: 135 $ date 136 codswaddle 137 138 139Bug Triage 140~~~~~~~~~~ 141 142Validating and confirming bugs is nearly as important as reporting them in the 143first place. It is valuable to know if a bug can be duplicated on a different 144machine, on a different filesystem, on a different architecture, with a 145different C library, and so forth. 146 147To see a listing of all the bugs currently filed against Busybox, look here: 148 149 http://bugs.lineo.com/db/pa/lbusybox.html 150 151If you have comments to add to a bug (can / can't duplicate, think a bug 152should be closed / reopened), please send it to [bugnumber]@bugs.lineo.com. 153The message you send will automatically be forwarded to the mailing list for 154all to see. 155 156 157Write Documentation 158~~~~~~~~~~~~~~~~~~~ 159 160Chances are, documentation in Busybox is either missing or needs improvement. 161Either way, help is welcome. 162 163Work is being done to automatically generate documentation from sources, 164especially from the usage.h file. If you want to correct the documentation, 165please make changes to the pre-generation parts, rather than the generated 166documentation. [More to come on this later...] 167 168It is preferred that modifications to documentation be submitted in patch 169format (more on this below), but we're a little more lenient when it comes to 170docs. You could, for example, just say "after the listing of the mount 171options, the following example would be helpful..." 172 173 174Consult Existing Sources 175~~~~~~~~~~~~~~~~~~~~~~~~ 176 177For a quick listing of "needs work" spots in the sources, cd into the Busybox 178directory and run the following: 179 180 for i in TODO FIXME XXX; do grep $i *.[ch]; done 181 182This will show all of the trouble spots or 'questionable' code. Pick a spot, 183any spot, these are all invitations for you to contribute. 184 185 186Consult The Bug-Tracking System 187~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 188 189Head to: http://bugs.lineo.com/db/pa/lBusybox.html and look at the bugs on 190there. Pick one you think you can fix, and fix it. If it's a wishlist item and 191someone's requesting a new feature, take a stab at adding it. Everything 192previously said about "reading the mailing list" and "coordinating with the 193applet maintainer" still applies. 194 195 196Add a New Applet 197~~~~~~~~~~~~~~~~ 198 199If you want to add a new applet to Busybox, we'd love to see it. However, 200before you write any code, please ask beforehand on the mailing list something 201like "Do you think applet 'foo' would be useful in Busybox?" or "Would you 202guys accept applet 'foo' into Busybox if I were to write it?" If the answer is 203"no" by the folks on the mailing list, then you've saved yourself some time. 204Conversely, you could get some positive responses from folks who might be 205interested in helping you implement it, or can recommend the best approach. 206Perhaps most importantly, this is your way of calling "dibs" on something and 207avoiding duplication of effort. 208 209Also, before you write a line of code, please read the 'new-applet-HOWTO.txt' 210file in the docs/ directory. 211 212 213Janitorial Work 214~~~~~~~~~~~~~~~ 215 216These are dirty jobs, but somebody's gotta do 'em. 217 218 - Converting applets to use getopt() for option processing. Type 'grep -L 219 getopt *.c' to get a listing of the applets that currently don't use 220 getopt. If a .c file processes no options, it should have a line that 221 reads: /* no options, no getopt */ somewhere in the file. 222 223 - Replace any "naked" calls to malloc, calloc, realloc, str[n]dup, fopen with 224 the x* equivalents found in utility.c. 225 226 - Security audits: 227 http://www.securityfocus.com/frames/?content=/forums/secprog/secure-programming.html 228 229 - Synthetic code removal: http://www.perl.com/pub/2000/06/commify.html - This 230 is very Perl-specific, but the advice given in here applies equally well to 231 C. 232 233 - C library funciton use audits: Verifying that functions are being used 234 properly (called with the right args), replacing unsafe library functions 235 with safer versions, making sure return codes are being checked, etc. 236 237 - Where appropriate, replace preprocessor defined macros and values with 238 compile-time equivalents. 239 240 - Style guide compliance. See: docs/style-guide.txt 241 242 - Add testcases to tests/testcases. 243 244 - Makefile improvements: 245 http://www.canb.auug.org.au/~millerp/rmch/recu-make-cons-harm.html 246 (I think the recursive problems are pretty much taken care of at this point, non?) 247 248 - "Ten Commandments" compliance: (this is a "maybe", certainly not as 249 important as any of the previous items.) 250 http://web.onetelnet.ch/~twolf/tw/c/ten_commandments.html 251 252Other useful links: 253 254 - the comp.lang.c FAQ: http://web.onetelnet.ch/~twolf/tw/c/index.html#Sources 255 256 257 258Submitting Patches To Busybox 259----------------------------- 260 261Here are some guidelines on how to submit a patch to Busybox. 262 263 264Making A Patch 265~~~~~~~~~~~~~~ 266 267If you've got anonymous CVS access set up, making a patch is simple. Just make 268sure you're in the busybox/ directory and type 'cvs diff -bwu > mychanges.patch'. 269You can send the resulting .patch file to the mailing list with a description 270of what it does. (But not before you test it! See the next section for some 271guidelines.) It is preferred that patches be sent as attachments, but it is 272not required. 273 274Also, feel free to help test other people's patches and reply to them with 275comments. You can apply a patch by saving it into your busybox/ directory and 276typing 'patch < mychanges.patch'. Then you can recompile, see if it runs, test 277if it works as advertised, and post your findings to the mailing list. 278 279NOTE: Please do not include extraneous or irrelevant changes in your patches. 280Please do not try to "bundle" two patches together into one. Make single, 281discreet changes on a per-patch basis. Sometimes you need to make a patch that 282touches code in many places, but these kind of patches are rare and should be 283coordinated with a maintainer. 284 285 286Testing Guidelines 287~~~~~~~~~~~~~~~~~~ 288 289It's considered good form to test your new feature before you submit a patch 290to the mailing list, and especially before you commit a change to CVS. Here 291are some guidelines on how to test your changes. 292 293 - Always test Busybox applets against GNU counterparts and make sure the 294 behavior / output is identical between the two. 295 296 - Try several different permutations and combinations of the features you're 297 adding (i.e., different combinations of command-line switches) and make sure 298 they all work; make sure one feature does not interfere with another. 299 300 - Make sure you test compiling against the source both with the feature 301 turned on and turned off in Config.h and make sure Busybox compiles cleanly 302 both ways. 303 304 - Run the multibuild.pl script in the tests directory and make sure 305 everything checks out OK. (Do this from within the busybox/ directory by 306 typing: 'tests/multibuild.pl'.) 307 308 309Making Sure Your Patch Doesn't Get Lost 310~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 311 312If you don't want your patch to be lost or forgotten, send it to the bug 313tracking system (http://bugs.lineo.com). You do this by emailing your patch in 314a message to submit@bugs.lineo.com with a subject line something like this: 315 316 [PATCH] - Adds "transmogrify" feature to "foo" 317 318In the body, you should have a pseudo-header that looks like the following: 319 320 Package: busybox 321 Version: v0.50pre (or whatever the current version is) 322 Severity: wishlist 323 324The remainder of the body should read along these lines: 325 326 This patch adds the "transmogrify" feature to the "foo" applet. I have 327 tested this on [arch] system(s) and it works. I have tested it against the 328 GNU counterparts and the outputs are identical. I have run the scripts in 329 the 'tests' directory and nothing breaks. 330 331Detailed instructions on how to submit a bug to the tracking system are at: 332 333 http://bugs.lineo.com/Reporting.html 334 335If you have a patch that will fix and close a reported bug, please send a 336message to [bugnumber]@bugs.lineo.com with your patch attached. It will catch 337people's attention if you have a subject line like the following: 338 339 [PATCH INCLUDED] - Fix attached, please apply and close this bug 340 341 342 343Improving Your Chances of Patch Acceptance 344------------------------------------------ 345 346Even after you send a brilliant patch to the mailing list, sometimes it can go 347unnoticed, un-replied-to, and sometimes (sigh) even lost. This is an 348unfortunate fact of life, but there are steps you can take to help your patch 349get noticed and convince a maintainer that it should be added: 350 351 352Be Succinct 353~~~~~~~~~~~ 354 355A patch that includes small, isolated, obvious changes is more likely to be 356accepted than a patch that touches code in lots of different places or makes 357sweeping, dubious changes. 358 359 360Back It Up 361~~~~~~~~~~ 362 363Hard facts on why your patch is better than the existing code will go a long 364way toward convincing maintainers that your patch should be included. 365Specifically, patches are more likely to be accepted if they are provably more 366correct, smaller, faster, simpler, or more maintainable than the existing 367code. 368 369Conversely, any patch that is supported with nothing more than "I think this 370would be cool" or "this patch is good because I say it is and I've got a Phd 371in Computer Science" will likely be ignored. 372 373 374Follow The Style Guide 375~~~~~~~~~~~~~~~~~~~~~~ 376 377It's considered good form to abide by the established coding style used in a 378project; Busybox is no exception. We have gone so far as to delineate the 379"elements of Busybox style" in the file docs/style-guide.txt. Please follow 380them. 381 382 383Work With Someone Else 384~~~~~~~~~~~~~~~~~~~~~~ 385 386Working on a patch in isolation is less effective than working with someone 387else for a variety of reasons. If another Busybox user is interested in what 388you're doing, then it's two (or more) voices instead of one that can petition 389for inclusion of the patch. You'll also have more people that can test your 390changes, or even offer suggestions on better approaches you could take. 391 392Getting other folks interested follows as a natural course if you've received 393responses from queries to applet maintainer or positive responses from folks 394on the mailing list. 395 396We've made strident efforts to put a useful "collaboration" infrastructure in 397place in the form of mailing lists, the bug tracking system, and CVS. Please 398use these resources. 399 400 401Send Patches to the Bug Tracking System 402~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 403 404This was mentioned above in the "Making Sure Your Patch Doesn't Get Lost" 405section, but it is worth mentioning again. A patch sent to the mailing list 406might be unnoticed and forgotten. A patch sent to the bug tracking system will 407be stored and closely connected to the bug it fixes. 408 409 410Be Polite 411~~~~~~~~~ 412 413The old saying "You'll catch more flies with honey than you will with vinegar" 414applies when submitting patches to the mailing list for approval. The way you 415present your patch is sometimes just as important as the actual patch itself 416(if not more so). Being rude to the maintainers is not an effective way to 417convince them that your patch should be included; it will likely have the 418opposite effect. 419 420 421 422Committing Changes to CVS 423------------------------- 424 425If you submit several patches that demonstrate that you are a skilled and wise 426coder, you may be invited to become a committer, thus enabling you to commit 427changes directly to CVS. This is nice because you don't have to wait for 428someone else to commit your change for you, you can just do it yourself. 429 430But note that this is a priviledge that comes with some responsibilities. You 431should test your changes before you commit them. You should also talk to an 432applet maintainer before you make any kind of sweeping changes to somebody 433else's code. Big changes should still go to the mailing list first. Remember, 434being wise, polite, and discreet is more important than being clever. 435 436 437When To Commit 438~~~~~~~~~~~~~~ 439 440Generally, you should feel free to commit a change if: 441 442 - Your changes are small and don't touch many files 443 - You are fixing a bug 444 - Somebody has told you that it's okay 445 - It's obviously the Right Thing 446 447The more of the above are true, the better it is to just commit a change 448directly to CVS. 449 450 451When Not To Commit 452~~~~~~~~~~~~~~~~~~ 453 454Even if you have commit rights, you should probably still post a patch to the 455mailing list if: 456 457 - Your changes are broad and touch many different files 458 - You are adding a feature 459 - Your changes are speculative or experimental (i.e., trying a new algorithm) 460 - You are not the maintainer and your changes make the maintainer cringe 461 462The more of the above are true, the better it is to post a patch to the 463mailing list instead of committing. 464 465 466 467Final Words 468----------- 469 470If all of this seems complicated, don't panic, it's really not that tough. If 471you're having difficulty following some of the steps outlined in this 472document don't worry, the folks on the Busybox mailing list are a fairly 473good-natured bunch and will work with you to help get your patches into shape 474or help you make contributions. 475 476 477