[3320] | 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 Git access set up, making a patch is simple. Just make
|
---|
| 233 | sure you're in the busybox/ directory and type:
|
---|
| 234 |
|
---|
| 235 | git diff -b -w > mychanges.patch
|
---|
| 236 |
|
---|
| 237 | You can send the resulting .patch file to the mailing list with a description
|
---|
| 238 | of what it does. (But not before you test it! See the next section for some
|
---|
| 239 | guidelines.) It is preferred that patches be sent as attachments, but it is
|
---|
| 240 | not required.
|
---|
| 241 |
|
---|
| 242 | Also, feel free to help test other people's patches and reply to them with
|
---|
| 243 | comments. You can apply a patch by saving it into your busybox/ directory and
|
---|
| 244 | typing:
|
---|
| 245 |
|
---|
| 246 | patch -p1 < mychanges.patch
|
---|
| 247 |
|
---|
| 248 | Then you can recompile, see if it runs, test if it works as advertised, and
|
---|
| 249 | post your findings to the mailing list.
|
---|
| 250 |
|
---|
| 251 | NOTE: Please do not include extraneous or irrelevant changes in your patches.
|
---|
| 252 | Please do not try to "bundle" two patches together into one. Make single,
|
---|
| 253 | discreet changes on a per-patch basis. Sometimes you need to make a patch that
|
---|
| 254 | touches code in many places, but these kind of patches are rare and should be
|
---|
| 255 | coordinated with a maintainer.
|
---|
| 256 |
|
---|
| 257 |
|
---|
| 258 | Testing Guidelines
|
---|
| 259 | ~~~~~~~~~~~~~~~~~~
|
---|
| 260 |
|
---|
| 261 | It's considered good form to test your new feature before you submit a patch
|
---|
| 262 | to the mailing list, and especially before you push a change to Git. Here
|
---|
| 263 | are 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 |
|
---|
| 281 | Making Sure Your Patch Doesn't Get Lost
|
---|
| 282 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
---|
| 283 |
|
---|
| 284 | If you don't want your patch to be lost or forgotten, send it to the busybox
|
---|
| 285 | mailing list with a subject line something like this:
|
---|
| 286 |
|
---|
| 287 | [PATCH] - Adds "transmogrify" feature to "foo"
|
---|
| 288 |
|
---|
| 289 | In 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 |
|
---|
| 295 | The 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 |
|
---|
| 304 | Improving Your Chances of Patch Acceptance
|
---|
| 305 | ------------------------------------------
|
---|
| 306 |
|
---|
| 307 | Even after you send a brilliant patch to the mailing list, sometimes it can go
|
---|
| 308 | unnoticed, un-replied-to, and sometimes (sigh) even lost. This is an
|
---|
| 309 | unfortunate fact of life, but there are steps you can take to help your patch
|
---|
| 310 | get noticed and convince a maintainer that it should be added:
|
---|
| 311 |
|
---|
| 312 |
|
---|
| 313 | Be Succinct
|
---|
| 314 | ~~~~~~~~~~~
|
---|
| 315 |
|
---|
| 316 | A patch that includes small, isolated, obvious changes is more likely to be
|
---|
| 317 | accepted than a patch that touches code in lots of different places or makes
|
---|
| 318 | sweeping, dubious changes.
|
---|
| 319 |
|
---|
| 320 |
|
---|
| 321 | Back It Up
|
---|
| 322 | ~~~~~~~~~~
|
---|
| 323 |
|
---|
| 324 | Hard facts on why your patch is better than the existing code will go a long
|
---|
| 325 | way toward convincing maintainers that your patch should be included.
|
---|
| 326 | Specifically, patches are more likely to be accepted if they are provably more
|
---|
| 327 | correct, smaller, faster, simpler, or more maintainable than the existing
|
---|
| 328 | code.
|
---|
| 329 |
|
---|
| 330 | Conversely, any patch that is supported with nothing more than "I think this
|
---|
| 331 | would be cool" or "this patch is good because I say it is and I've got a Phd
|
---|
| 332 | in Computer Science" will likely be ignored.
|
---|
| 333 |
|
---|
| 334 |
|
---|
| 335 | Follow The Style Guide
|
---|
| 336 | ~~~~~~~~~~~~~~~~~~~~~~
|
---|
| 337 |
|
---|
| 338 | It's considered good form to abide by the established coding style used in a
|
---|
| 339 | project; 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
|
---|
| 341 | them.
|
---|
| 342 |
|
---|
| 343 |
|
---|
| 344 | Work With Someone Else
|
---|
| 345 | ~~~~~~~~~~~~~~~~~~~~~~
|
---|
| 346 |
|
---|
| 347 | Working on a patch in isolation is less effective than working with someone
|
---|
| 348 | else for a variety of reasons. If another Busybox user is interested in what
|
---|
| 349 | you're doing, then it's two (or more) voices instead of one that can petition
|
---|
| 350 | for inclusion of the patch. You'll also have more people that can test your
|
---|
| 351 | changes, or even offer suggestions on better approaches you could take.
|
---|
| 352 |
|
---|
| 353 | Getting other folks interested follows as a natural course if you've received
|
---|
| 354 | responses from queries to applet maintainer or positive responses from folks
|
---|
| 355 | on the mailing list.
|
---|
| 356 |
|
---|
| 357 | We've made strident efforts to put a useful "collaboration" infrastructure in
|
---|
| 358 | place in the form of mailing lists, the bug tracking system, and Git. Please
|
---|
| 359 | use these resources.
|
---|
| 360 |
|
---|
| 361 |
|
---|
| 362 | Send Patches to the Bug Tracking System
|
---|
| 363 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
---|
| 364 |
|
---|
| 365 | This was mentioned above in the "Making Sure Your Patch Doesn't Get Lost"
|
---|
| 366 | section, but it is worth mentioning again. A patch sent to the mailing list
|
---|
| 367 | might be unnoticed and forgotten. A patch sent to the bug tracking system will
|
---|
| 368 | be stored and closely connected to the bug it fixes.
|
---|
| 369 |
|
---|
| 370 |
|
---|
| 371 | Be Polite
|
---|
| 372 | ~~~~~~~~~
|
---|
| 373 |
|
---|
| 374 | The old saying "You'll catch more flies with honey than you will with vinegar"
|
---|
| 375 | applies when submitting patches to the mailing list for approval. The way you
|
---|
| 376 | present 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
|
---|
| 378 | convince them that your patch should be included; it will likely have the
|
---|
| 379 | opposite effect.
|
---|
| 380 |
|
---|
| 381 |
|
---|
| 382 |
|
---|
| 383 | Pushing Changes to Git
|
---|
| 384 | ----------------------
|
---|
| 385 |
|
---|
| 386 | If you submit several patches that demonstrate that you are a skilled and wise
|
---|
| 387 | coder, you may be invited to become a committer, thus enabling you to push
|
---|
| 388 | changes directly to Git. This is nice because you don't have to wait for
|
---|
| 389 | someone else to push your change for you, you can just do it yourself.
|
---|
| 390 |
|
---|
| 391 | But note that this is a privilege that comes with some responsibilities. You
|
---|
| 392 | should test your changes before you push them. You should also talk to an
|
---|
| 393 | applet maintainer before you make any kind of sweeping changes to somebody
|
---|
| 394 | else's code. Big changes should still go to the mailing list first. Remember,
|
---|
| 395 | being wise, polite, and discreet is more important than being clever.
|
---|
| 396 |
|
---|
| 397 | For more information on Git push access, see:
|
---|
| 398 |
|
---|
| 399 | http://busybox.net/developer.html
|
---|
| 400 |
|
---|
| 401 |
|
---|
| 402 | When To Push
|
---|
| 403 | ~~~~~~~~~~~~
|
---|
| 404 |
|
---|
| 405 | Generally, 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 |
|
---|
| 412 | The more of the above are true, the better it is to just push a change
|
---|
| 413 | directly to Git.
|
---|
| 414 |
|
---|
| 415 |
|
---|
| 416 | When Not To Push
|
---|
| 417 | ~~~~~~~~~~~~~~~~
|
---|
| 418 |
|
---|
| 419 | Even if you have push access, you should probably still post a patch to the
|
---|
| 420 | mailing 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 |
|
---|
| 427 | The more of the above are true, the better it is to post a patch to the
|
---|
| 428 | mailing list instead of pushing.
|
---|
| 429 |
|
---|
| 430 |
|
---|
| 431 |
|
---|
| 432 | Final Words
|
---|
| 433 | -----------
|
---|
| 434 |
|
---|
| 435 | If all of this seems complicated, don't panic, it's really not that tough. If
|
---|
| 436 | you're having difficulty following some of the steps outlined in this
|
---|
| 437 | document don't worry, the folks on the Busybox mailing list are a fairly
|
---|
| 438 | good-natured bunch and will work with you to help get your patches into shape
|
---|
| 439 | or help you make contributions.
|
---|