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.net/ 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 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 development tree, please look at the 29following links: 30 31 http://busybox.net/source.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://busybox.net/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 would be a good idea to join the mailing 49list. 50 51A web-based sign-up form can be found here: 52 53 http://busybox.net/mailman/listinfo/busybox 54 55 56Coordinate with the Applet Maintainer 57~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 58 59Some (not all) of the applets in Busybox are "owned" by a maintainer who has 60put significant effort into it and is probably more familiar with it than 61others. To find the maintainer of an applet, look at the top of the .c file 62for a name following the word 'Copyright' or 'Written by' or 'Maintainer'. 63 64Before plunging ahead, it's a good idea to send a message to the mailing list 65that 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 67want to CC the maintainer (if any) with your question. 68 69 70 71Areas Where You Can Help 72------------------------ 73 74Busybox can always use improvement! If you're looking for ways to help, there 75are a variety of areas where you could help. 76 77 78What Busybox Doesn't Need 79~~~~~~~~~~~~~~~~~~~~~~~~~ 80 81Before listing the areas where you _can_ help, it's worthwhile to mention the 82areas where you shouldn't bother. While Busybox strives to be the "Swiss Army 83Knife" 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 102Bug Reporting 103~~~~~~~~~~~~~ 104 105If you find bugs, please submit a detailed bug report to the busybox mailing 106list at busybox@busybox.net. A well-written bug report should include a 107transcript of a shell session that demonstrates the bad behavior and enables 108anyone else to duplicate the bug on their own machine. The following is such 109an 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 134Note the careful description and use of examples showing not only what BusyBox 135does, but also a counter example showing what an equivalent GNU app does. Bug 136reports lacking such detail may never be fixed... Thanks for understanding. 137 138 139 140Write Documentation 141~~~~~~~~~~~~~~~~~~~ 142 143Chances are, documentation in Busybox is either missing or needs improvement. 144Either way, help is welcome. 145 146Work is being done to automatically generate documentation from sources, 147especially from the usage.h file. If you want to correct the documentation, 148please make changes to the pre-generation parts, rather than the generated 149documentation. [More to come on this later...] 150 151It is preferred that modifications to documentation be submitted in patch 152format (more on this below), but we're a little more lenient when it comes to 153docs. You could, for example, just say "after the listing of the mount 154options, the following example would be helpful..." 155 156 157Consult Existing Sources 158~~~~~~~~~~~~~~~~~~~~~~~~ 159 160For a quick listing of "needs work" spots in the sources, cd into the Busybox 161directory and run the following: 162 163 for i in TODO FIXME XXX; do find -name '*.[ch]'|xargs grep $i; done 164 165This will show all of the trouble spots or 'questionable' code. Pick a spot, 166any spot, these are all invitations for you to contribute. 167 168 169Add a New Applet 170~~~~~~~~~~~~~~~~ 171 172If you want to add a new applet to Busybox, we'd love to see it. However, 173before you write any code, please ask beforehand on the mailing list something 174like "Do you think applet 'foo' would be useful in Busybox?" or "Would you 175guys 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. 177Conversely, you could get some positive responses from folks who might be 178interested in helping you implement it, or can recommend the best approach. 179Perhaps most importantly, this is your way of calling "dibs" on something and 180avoiding duplication of effort. 181 182Also, before you write a line of code, please read the 'new-applet-HOWTO.txt' 183file in the docs/ directory. 184 185 186Janitorial Work 187~~~~~~~~~~~~~~~ 188 189These 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 217Other useful links: 218 219 - the comp.lang.c FAQ: http://home.datacomm.ch/t_wolf/tw/c/index.html#Sources 220 221 222 223Submitting Patches To Busybox 224----------------------------- 225 226Here are some guidelines on how to submit a patch to Busybox. 227 228 229Making A Patch 230~~~~~~~~~~~~~~ 231 232If you've got anonymous Git access set up, making a patch is simple. Just make 233sure you're in the busybox/ directory and type: 234 235 git diff -b -w > mychanges.patch 236 237You can send the resulting .patch file to the mailing list with a description 238of what it does. (But not before you test it! See the next section for some 239guidelines.) It is preferred that patches be sent as attachments, but it is 240not required. 241 242Also, feel free to help test other people's patches and reply to them with 243comments. You can apply a patch by saving it into your busybox/ directory and 244typing: 245 246 patch -p1 < mychanges.patch 247 248Then you can recompile, see if it runs, test if it works as advertised, and 249post your findings to the mailing list. 250 251NOTE: Please do not include extraneous or irrelevant changes in your patches. 252Please do not try to "bundle" two patches together into one. Make single, 253discreet changes on a per-patch basis. Sometimes you need to make a patch that 254touches code in many places, but these kind of patches are rare and should be 255coordinated with a maintainer. 256 257 258Testing Guidelines 259~~~~~~~~~~~~~~~~~~ 260 261It's considered good form to test your new feature before you submit a patch 262to the mailing list, and especially before you push a change to Git. Here 263are some guidelines on how to test your changes. 264 265 - Always test Busybox applets against GNU counterparts and make sure the 266 behavior / output is identical between the two. 267 268 - Try several different permutations and combinations of the features you're 269 adding (i.e., different combinations of command-line switches) and make sure 270 they all work; make sure one feature does not interfere with another. 271 272 - Make sure you test compiling against the source both with the feature 273 turned on and turned off in Config.h and make sure Busybox compiles cleanly 274 both ways. 275 276 - Run the multibuild.pl script in the tests directory and make sure 277 everything checks out OK. (Do this from within the busybox/ directory by 278 typing: 'tests/multibuild.pl'.) 279 280 281Making Sure Your Patch Doesn't Get Lost 282~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 283 284If you don't want your patch to be lost or forgotten, send it to the busybox 285mailing list with a subject line something like this: 286 287 [PATCH] - Adds "transmogrify" feature to "foo" 288 289In the body, you should have a pseudo-header that looks like the following: 290 291 Package: busybox 292 Version: v1.01pre (or whatever the current version is) 293 Severity: wishlist 294 295The remainder of the body should read along these lines: 296 297 This patch adds the "transmogrify" feature to the "foo" applet. I have 298 tested this on [arch] system(s) and it works. I have tested it against the 299 GNU counterparts and the outputs are identical. I have run the scripts in 300 the 'tests' directory and nothing breaks. 301 302 303 304Improving Your Chances of Patch Acceptance 305------------------------------------------ 306 307Even after you send a brilliant patch to the mailing list, sometimes it can go 308unnoticed, un-replied-to, and sometimes (sigh) even lost. This is an 309unfortunate fact of life, but there are steps you can take to help your patch 310get noticed and convince a maintainer that it should be added: 311 312 313Be Succinct 314~~~~~~~~~~~ 315 316A patch that includes small, isolated, obvious changes is more likely to be 317accepted than a patch that touches code in lots of different places or makes 318sweeping, dubious changes. 319 320 321Back It Up 322~~~~~~~~~~ 323 324Hard facts on why your patch is better than the existing code will go a long 325way toward convincing maintainers that your patch should be included. 326Specifically, patches are more likely to be accepted if they are provably more 327correct, smaller, faster, simpler, or more maintainable than the existing 328code. 329 330Conversely, any patch that is supported with nothing more than "I think this 331would be cool" or "this patch is good because I say it is and I've got a Phd 332in Computer Science" will likely be ignored. 333 334 335Follow The Style Guide 336~~~~~~~~~~~~~~~~~~~~~~ 337 338It's considered good form to abide by the established coding style used in a 339project; Busybox is no exception. We have gone so far as to delineate the 340"elements of Busybox style" in the file docs/style-guide.txt. Please follow 341them. 342 343 344Work With Someone Else 345~~~~~~~~~~~~~~~~~~~~~~ 346 347Working on a patch in isolation is less effective than working with someone 348else for a variety of reasons. If another Busybox user is interested in what 349you're doing, then it's two (or more) voices instead of one that can petition 350for inclusion of the patch. You'll also have more people that can test your 351changes, or even offer suggestions on better approaches you could take. 352 353Getting other folks interested follows as a natural course if you've received 354responses from queries to applet maintainer or positive responses from folks 355on the mailing list. 356 357We've made strident efforts to put a useful "collaboration" infrastructure in 358place in the form of mailing lists, the bug tracking system, and Git. Please 359use these resources. 360 361 362Send Patches to the Bug Tracking System 363~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 364 365This was mentioned above in the "Making Sure Your Patch Doesn't Get Lost" 366section, but it is worth mentioning again. A patch sent to the mailing list 367might be unnoticed and forgotten. A patch sent to the bug tracking system will 368be stored and closely connected to the bug it fixes. 369 370 371Be Polite 372~~~~~~~~~ 373 374The old saying "You'll catch more flies with honey than you will with vinegar" 375applies when submitting patches to the mailing list for approval. The way you 376present your patch is sometimes just as important as the actual patch itself 377(if not more so). Being rude to the maintainers is not an effective way to 378convince them that your patch should be included; it will likely have the 379opposite effect. 380 381 382 383Pushing Changes to Git 384---------------------- 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 push 388changes directly to Git. This is nice because you don't have to wait for 389someone else to push your change for you, you can just do it yourself. 390 391But note that this is a privilege that comes with some responsibilities. You 392should test your changes before you push them. You should also talk to an 393applet maintainer before you make any kind of sweeping changes to somebody 394else's code. Big changes should still go to the mailing list first. Remember, 395being wise, polite, and discreet is more important than being clever. 396 397For more information on Git push access, see: 398 399 http://busybox.net/developer.html 400 401 402When To Push 403~~~~~~~~~~~~ 404 405Generally, you should feel free to push a change if: 406 407 - Your changes are small and don't touch many files 408 - You are fixing a bug 409 - Somebody has told you that it's okay 410 - It's obviously the Right Thing 411 412The more of the above are true, the better it is to just push a change 413directly to Git. 414 415 416When Not To Push 417~~~~~~~~~~~~~~~~ 418 419Even if you have push access, you should probably still post a patch to the 420mailing list if: 421 422 - Your changes are broad and touch many different files 423 - You are adding a feature 424 - Your changes are speculative or experimental (i.e., trying a new algorithm) 425 - You are not the maintainer and your changes make the maintainer cringe 426 427The more of the above are true, the better it is to post a patch to the 428mailing list instead of pushing. 429 430 431 432Final Words 433----------- 434 435If all of this seems complicated, don't panic, it's really not that tough. If 436you're having difficulty following some of the steps outlined in this 437document don't worry, the folks on the Busybox mailing list are a fairly 438good-natured bunch and will work with you to help get your patches into shape 439or help you make contributions. 440