diff options
| author | Mark Whitley <markw@lineo.com> | 2001-03-02 19:14:25 +0000 |
|---|---|---|
| committer | Mark Whitley <markw@lineo.com> | 2001-03-02 19:14:25 +0000 |
| commit | 3b565cdf910a95e0955d3480fcd617fa5dbda78b (patch) | |
| tree | 7c36bee48bb6dce655a4535311a928f3b22464d9 /docs/contributing.txt | |
| parent | 85adecb668cec178d32775547ebde4eb4f1e9149 (diff) | |
| download | busybox-w32-3b565cdf910a95e0955d3480fcd617fa5dbda78b.tar.gz busybox-w32-3b565cdf910a95e0955d3480fcd617fa5dbda78b.tar.bz2 busybox-w32-3b565cdf910a95e0955d3480fcd617fa5dbda78b.zip | |
Added 'How to contribute to Busybox' doc.
Diffstat (limited to 'docs/contributing.txt')
| -rw-r--r-- | docs/contributing.txt | 390 |
1 files changed, 390 insertions, 0 deletions
diff --git a/docs/contributing.txt b/docs/contributing.txt new file mode 100644 index 000000000..696e63c2c --- /dev/null +++ b/docs/contributing.txt | |||
| @@ -0,0 +1,390 @@ | |||
| 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.lineo.com | ||
| 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 from CVS | ||
| 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 worked | ||
| 25 | on the area you had in mind and your patch might already be obsolete. | ||
| 26 | |||
| 27 | For information on how to check out Busybox from CVS, please look at the | ||
| 28 | following links: | ||
| 29 | |||
| 30 | http://oss.lineo.com/cvs_anon.html | ||
| 31 | http://oss.lineo.com/cvs_howto.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://opensource.lineo.com/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's a good idea to join the mailing list. | ||
| 49 | |||
| 50 | A web-based sign-up form can be found here: | ||
| 51 | |||
| 52 | http://opensource.lineo.com/mailman/listinfo/busybox | ||
| 53 | |||
| 54 | |||
| 55 | Coordinate with the Applet Maintainer | ||
| 56 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 57 | |||
| 58 | Some (not all) of the applets in Busybox are "owned" by a maintainer who has | ||
| 59 | put significant effort into it and is probably more familiar with it than | ||
| 60 | others. To find the maintainer of an applet, look at the top of the .c file | ||
| 61 | for a name following the word 'Copyright' or 'Written by'. | ||
| 62 | |||
| 63 | Before plunging ahead, it's a good idea to send a message to the mailing list | ||
| 64 | that says: "Hey, I was thinking about adding the 'transmogrify' feature to the | ||
| 65 | 'foo' applet. Would this be useful? Is anyone else working on it?" You might | ||
| 66 | want to CC the maintainer (if any) with your question. | ||
| 67 | |||
| 68 | |||
| 69 | |||
| 70 | Areas Where You Can Help | ||
| 71 | ------------------------ | ||
| 72 | |||
| 73 | Busybox can always use improvement! If you're looking for ways to help, there | ||
| 74 | there are a variety of areas where you could help. | ||
| 75 | |||
| 76 | |||
| 77 | What Busybox Doesn't Need | ||
| 78 | ~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 79 | |||
| 80 | Before listing the areas where you _can_ help, it's worthwhile to mention the | ||
| 81 | areas where you shouldn't bother. While Busybox strives to be the "Swiss Army | ||
| 82 | Knife" of embedded Linux, there are some applets that will not be accepted: | ||
| 83 | |||
| 84 | - Any filesystem manipulation tools: Busybox is filesystem independent and | ||
| 85 | we do not want to start adding mkfs/fsck tools for every (or any) | ||
| 86 | filesystem under the sun. (fsck_minix.c and mkfs_minix.c are living on | ||
| 87 | borrowed time.) There are far too many of these tools out there. Use | ||
| 88 | the upstream version. Not everything has to be part of Busybox. | ||
| 89 | |||
| 90 | - Any partitioning tools: Partitioning a device is typically done once and | ||
| 91 | only once, and tools which do this generally do not need to reside on the | ||
| 92 | target device (esp a flash device). If you need a partitioning tool, grab | ||
| 93 | one (such as fdisk, sfdisk, or cfdisk from util-linux) and use that, but | ||
| 94 | don't try to merge it into busybox. These are nasty and complex and we | ||
| 95 | don't want to maintain them. | ||
| 96 | |||
| 97 | - Any disk, device, or media-specific tools: Use the -utils or -tools package | ||
| 98 | that was designed for your device; don't try to shoehorn them into Busybox. | ||
| 99 | |||
| 100 | - Any architecture specific tools: Busybox is (or should be) architecture | ||
| 101 | independent. Do not send us tools that cannot be used across multiple | ||
| 102 | platforms / arches. | ||
| 103 | |||
| 104 | |||
| 105 | Bug Reporting | ||
| 106 | ~~~~~~~~~~~~~ | ||
| 107 | |||
| 108 | If you find a bug in Busybox, you can send a bug report to our bug tracking | ||
| 109 | system (homepage: http://bugs.lineo.com). Instructions on how to send a bug | ||
| 110 | report to the tracking system can be found at: | ||
| 111 | |||
| 112 | http://bugs.lineo.com/Reporting.html | ||
| 113 | |||
| 114 | The README file that comes with Busybox also describes how to submit a bug. | ||
| 115 | |||
| 116 | A well-written bug report will include a transcript of a shell session that | ||
| 117 | demonstrates the bad behavior and enables anyone else to duplicate the bug on | ||
| 118 | their own machine. | ||
| 119 | |||
| 120 | |||
| 121 | Bug Triage | ||
| 122 | ~~~~~~~~~~ | ||
| 123 | |||
| 124 | Validating and confirming bugs is nearly as important as reporting them in the | ||
| 125 | first place. It is valuable to know if a bug can be duplicated on a different | ||
| 126 | machine, on a different filesystem, on a different architecture, with a | ||
| 127 | different C library, and so forth. | ||
| 128 | |||
| 129 | To see a listing of all the bugs currently filed against Busybox, look here: | ||
| 130 | |||
| 131 | http://bugs.lineo.com/db/pa/lbusybox.html | ||
| 132 | |||
| 133 | If you have comments to add to a bug (can / can't duplicate, think a bug | ||
| 134 | should be closed / reopened), please send it to [bugnumber]@bugs.lineo.com. | ||
| 135 | The message you send will automatically be forwarded to the mailing list for | ||
| 136 | all to see. | ||
| 137 | |||
| 138 | |||
| 139 | Write Documentation | ||
| 140 | ~~~~~~~~~~~~~~~~~~~ | ||
| 141 | |||
| 142 | Chances are, documentation in Busybox is either missing or needs improvement. | ||
| 143 | Either way, help is welcome. | ||
| 144 | |||
| 145 | Work is being done to automatically generate documentation from sources, | ||
| 146 | especially from the usage.h file. If you want to correct the documentation, | ||
| 147 | please make changes to the pre-generation parts, rather than the generated | ||
| 148 | documentation. [More to come on this later...] | ||
| 149 | |||
| 150 | It is preferred that modifications to documentation be submitted in patch | ||
| 151 | format (more on this below), but we're a little more lenient when it comes to | ||
| 152 | docs. You could, for example, just say "after the listing of the mount | ||
| 153 | options, the following example would be helpful..." | ||
| 154 | |||
| 155 | |||
| 156 | Consult Existing Sources | ||
| 157 | ~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 158 | |||
| 159 | For a quick listing of "needs work" spots in the sources, cd into the Busybox | ||
| 160 | directory and run the following: | ||
| 161 | |||
| 162 | for i in TODO FIXME XXX; do grep $i *.[ch]; done | ||
| 163 | |||
| 164 | This will show all of the trouble spots or 'questionable' code. Pick a spot, | ||
| 165 | any spot, these are all invitations for you to contribute. | ||
| 166 | |||
| 167 | |||
| 168 | Consult The Bug-Tracking System | ||
| 169 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 170 | |||
| 171 | Head to: http://bugs.lineo.com/db/pa/lBusybox.html and look at the bugs on | ||
| 172 | there. Pick one you think you can fix, and fix it. If it's a wishlist item and | ||
| 173 | someone's requesting a new feature, take a stab at adding it. Everything | ||
| 174 | previously said about "reading the mailing list" and "coordinating with the | ||
| 175 | applet maintainer" still applies. | ||
| 176 | |||
| 177 | |||
| 178 | Add a New Applet | ||
| 179 | ~~~~~~~~~~~~~~~~ | ||
| 180 | |||
| 181 | If you want to add a new applet to Busybox, we'd love to see it. However, | ||
| 182 | before you write any code, please ask beforehand on the mailing list something | ||
| 183 | like "Do you think applet 'foo' would be useful in Busybox?" or "Would you | ||
| 184 | guys accept applet 'foo' into Busybox if I were to write it?" If the answer is | ||
| 185 | "no" by the folks on the mailing list, then you've saved yourself some time. | ||
| 186 | Conversely, you could get some positive responses from folks who might be | ||
| 187 | interested in helping you implement it, or can recommend the best approach. | ||
| 188 | Perhaps most importantly, this is your way of calling "dibs" on something and | ||
| 189 | avoiding duplication of effort. | ||
| 190 | |||
| 191 | Also, before you write a line of code, please read the 'new-applet-HOWTO.txt' | ||
| 192 | file in the docs/ directory. | ||
| 193 | |||
| 194 | |||
| 195 | Janitorial Work | ||
| 196 | ~~~~~~~~~~~~~~~ | ||
| 197 | |||
| 198 | These are dirty jobs, but somebody's gotta do 'em. | ||
| 199 | |||
| 200 | - Security audits: | ||
| 201 | http://www.securityfocus.com/frames/?content=/forums/secprog/secure-programming.html | ||
| 202 | |||
| 203 | - Synthetic code removal: http://www.perl.com/pub/2000/06/commify.html - This | ||
| 204 | is very Perl-specific, but the advice given in here applies equally well to | ||
| 205 | C. | ||
| 206 | |||
| 207 | - C library funciton use audits: Verifying that functions are being used | ||
| 208 | properly (called with the right args), replacing unsafe library functions | ||
| 209 | with safer versions, making sure return codes are being checked, etc. | ||
| 210 | |||
| 211 | - Where appropriate, replace preprocessor defined macros and values with | ||
| 212 | compile-time equivalents. | ||
| 213 | |||
| 214 | - Makefile improvements: | ||
| 215 | http://www.canb.auug.org.au/~millerp/rmch/recu-make-cons-harm.html | ||
| 216 | (I think the recursive problems are pretty much taken care of at this point, non?) | ||
| 217 | |||
| 218 | - "Ten Commandments" compliance: (this is a "maybe", certainly not as | ||
| 219 | important as any of the previous items.) | ||
| 220 | http://web.onetelnet.ch/~twolf/tw/c/ten_commandments.html | ||
| 221 | |||
| 222 | Other useful links: | ||
| 223 | |||
| 224 | - the comp.lang.c FAQ: http://web.onetelnet.ch/~twolf/tw/c/index.html#Sources | ||
| 225 | |||
| 226 | |||
| 227 | |||
| 228 | Submitting Patches To Busybox | ||
| 229 | ----------------------------- | ||
| 230 | |||
| 231 | Here are some guidelines on how to submit a patch to Busybox. | ||
| 232 | |||
| 233 | |||
| 234 | Making A Patch | ||
| 235 | ~~~~~~~~~~~~~~ | ||
| 236 | |||
| 237 | If you've got anonymous CVS access set up, making a patch is simple. Just make | ||
| 238 | sure you're in the busybox/ directory and type 'cvs diff -bwu > mychanges.patch'. | ||
| 239 | You can send the resulting .patch file to the mailing list with a description | ||
| 240 | of what it does. (But not before you test it! See the next section for some | ||
| 241 | guidelines.) It is preferred that patches be sent as attachments, but it is | ||
| 242 | not required. | ||
| 243 | |||
| 244 | Also, feel free to help test other people's patches and reply to them with | ||
| 245 | comments. You can apply a patch by saving it into your busybox/ directory and | ||
| 246 | typing 'patch < mychanges.patch'. Then you can recompile, see if it runs, test | ||
| 247 | if it works as advertised, and post your findings to the mailing list. | ||
| 248 | |||
| 249 | NOTE: Please do not include extraneous or irrelevant changes in your patches. | ||
| 250 | Please do not try to "bundle" two patches together into one. Make single, | ||
| 251 | discreet changes on a per-patch basis. Sometimes you need to make a patch that | ||
| 252 | touches code in many places, but these kind of patches are rare and should be | ||
| 253 | coordinated with a maintainer. | ||
| 254 | |||
| 255 | |||
| 256 | Testing Guidelines | ||
| 257 | ~~~~~~~~~~~~~~~~~~ | ||
| 258 | |||
| 259 | It's considered good form to test your new feature before you submit a patch | ||
| 260 | to the mailing list, and especially before you commit a change to CVS. Here | ||
| 261 | are some guidelines on how to test your changes. | ||
| 262 | |||
| 263 | - Always test Busybox applets against GNU counterparts and make sure the | ||
| 264 | behavior / output is identical between the two. | ||
| 265 | |||
| 266 | - Try several different permutations and combinations of the features you're | ||
| 267 | adding (i.e. different combinations of command-line switches) and make sure | ||
| 268 | they all work; make sure one feature does not interfere with another. | ||
| 269 | |||
| 270 | - Make sure you test compiling against the source both with the feature | ||
| 271 | turned on and turned off in Config.h and make sure Busybox compiles cleanly | ||
| 272 | both ways. | ||
| 273 | |||
| 274 | - Run the multibuild.pl script in the tests directory and make sure | ||
| 275 | everything checks out OK. (Do this from within the busybox/ directory by | ||
| 276 | typing: 'tests/multibuild.pl'.) | ||
| 277 | |||
| 278 | |||
| 279 | Making Sure Your Patch Doesn't Get Lost | ||
| 280 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| 281 | |||
| 282 | If you don't want your patch to be lost or forgotten, send it to the bug | ||
| 283 | tracking system (http://bugs.lineo.com). You do this by emailing your patch in | ||
| 284 | a message to submit@bugs.lineo.com with a subject line something like this: | ||
| 285 | |||
| 286 | [PATCH] - Adds "transmogrify" feature to "foo" | ||
| 287 | |||
| 288 | In the body, you should have a pseudo-header that looks like the following: | ||
| 289 | |||
| 290 | Package: busybox | ||
| 291 | Version: v0.50pre (or whatever the current version is) | ||
| 292 | Severity: wishlist | ||
| 293 | |||
| 294 | The remainder of the body should read along these lines: | ||
| 295 | |||
| 296 | This patch adds the "transmogrify" feature to the "foo" applet. I have | ||
| 297 | tested this on [arch] system(s) and it works. I have tested it against the | ||
| 298 | GNU counterparts and the outputs are identical. I have run the scripts in | ||
| 299 | the 'tests' directory and nothing breaks. | ||
| 300 | |||
| 301 | Detailed instructions on how to submit a bug to the tracking system are at: | ||
| 302 | |||
| 303 | http://bugs.lineo.com/Reporting.html | ||
| 304 | |||
| 305 | |||
| 306 | |||
| 307 | Improving Your Chances of Patch Acceptance | ||
| 308 | ------------------------------------------ | ||
| 309 | |||
| 310 | Even after you send a brilliant patch to the mailing list, sometimes it can go | ||
| 311 | unnoticed, un-replied-to, and sometimes (sigh) even lost. This is an | ||
| 312 | unfortunate fact of life, but there are steps you can take to help your patch | ||
| 313 | get noticed and convince a maintainer that it should be added: | ||
| 314 | |||
| 315 | |||
| 316 | Be Succinct | ||
| 317 | ~~~~~~~~~~~ | ||
| 318 | |||
| 319 | A patch that includes small, isolated, obvious changes is more likely to be | ||
| 320 | accepted than a patch that touches code in lots of different places or makes | ||
| 321 | sweeping, dubious changes. | ||
| 322 | |||
| 323 | |||
| 324 | Back It Up | ||
| 325 | ~~~~~~~~~~ | ||
| 326 | |||
| 327 | Hard facts on why your patch is better than the existing code will go a long | ||
| 328 | way toward convincing maintainers that your patch should be included. | ||
| 329 | Specifically, patches are more likely to be accepted if they are provably more | ||
| 330 | correct, smaller, faster, simpler, or more maintainable than the existing | ||
| 331 | code. | ||
| 332 | |||
| 333 | Conversely, any patch that is supported with nothing more than "I think this | ||
| 334 | would be cool" or "this patch is good because I say it is and I've got a Phd | ||
| 335 | in Computer Science" will likely be ignored. | ||
| 336 | |||
| 337 | |||
| 338 | Follow The Style Guide | ||
| 339 | ~~~~~~~~~~~~~~~~~~~~~~ | ||
| 340 | |||
| 341 | It's considered good form to abide by the established coding style used in a | ||
| 342 | project; Busybox is no exception. We have gone so far as to delineate the | ||
| 343 | "elements of Busybox style" in the file docs/style-guide.txt. Please follow | ||
| 344 | them. | ||
| 345 | |||
| 346 | |||
| 347 | Work With Someone Else | ||
| 348 | ~~~~~~~~~~~~~~~~~~~~~~ | ||
| 349 | |||
| 350 | Working on a patch in isolation is less effective than working with someone | ||
| 351 | else for a variety of reasons. If another Busybox user is interested in what | ||
| 352 | you're doing, then it's two (or more) voices instead of one that can petition | ||
| 353 | for inclusion of the patch. You'll also have more people that can test your | ||
| 354 | changes, or even offer suggestions on better approaches you could take. | ||
| 355 | |||
| 356 | Getting other folks interested follows as a natural course if you've received | ||
| 357 | responses from queries to applet maintainer or positive responses from folks | ||
| 358 | on the mailing list. | ||
| 359 | |||
| 360 | We've made strident efforts to put a useful "collaboration" infrastructure in | ||
| 361 | place in the form of mailing lists, the bug tracking system, and CVS. Please | ||
| 362 | use these resources. | ||
| 363 | |||
| 364 | |||
| 365 | Be Polite | ||
| 366 | ~~~~~~~~~ | ||
| 367 | |||
| 368 | The old saying "You'll catch more flies with honey than you will with vinegar" | ||
| 369 | applies when submitting patches to the mailing list for approval. The way you | ||
| 370 | present your patch is sometimes just as important as the actual patch itself | ||
| 371 | (if not more so). Being rude to the maintainers is not an effective way to | ||
| 372 | convince them that your patch should be included; it will likely have the | ||
| 373 | opposite effect. | ||
| 374 | |||
| 375 | |||
| 376 | |||
| 377 | Final Words | ||
| 378 | ----------- | ||
| 379 | |||
| 380 | If all of this seems complicated, don't panic, it's really not that tough. If | ||
| 381 | you're having difficulty following some of the steps outlined in this | ||
| 382 | document don't worry, the folks on the Busybox mailing list are a fairly | ||
| 383 | good-natured bunch and will work with you to help get your patches into shape | ||
| 384 | or help you make contributions. | ||
| 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 commit | ||
| 388 | changes directly to CVS. | ||
| 389 | |||
| 390 | |||