h1. Contributing Buildr is a community effort, and we welcome all contributors. Here's your chance to get involved and help your fellow developers. h2. Mailing Lists We run two mailing lists, the "buildr-user":http://mail-archives.apache.org/mod_mbox/incubator-buildr-user/ mailing list for developers working with Buildr, that would be you if you're using Buildr or interested in using it. There's the "buildr-dev":http://mail-archives.apache.org/mod_mbox/incubator-buildr-dev/ mailing list for talking about development of Buildr itself, and "commits":http://mail-archives.apache.org/mod_mbox/incubator-buildr-commits/ mailing list for following SVN commits and JIRA issues. Check the "mailing lists":mailing_lists.html page for more information on subscribing, searching and posting to the mailing list. h2. Bugs (aka Issues) We really do try to keep bugs to a minimum, and anticipate everything you'll ever want to do with Buildr. We're also, not perfect. So you may have found a bug, or have an enhancement in mind, or better yet, a patch to contribute. Here's what you can do. If it's a bug, enhancement or patch, add it to "JIRA":http://issues.apache.org/jira/browse/Buildr. For trivial stuff, that's good enough. If it needs more attention, start a discussion over on the mailing list. We will still use JIRA to log the progress, but the mailing list is a better place for talking things through. When reporting a bug, please tell us which version of Ruby, Buildr and Java you are using, and also which operating system you are on: {{{!sh $ ruby --version $ buildr --version $ java --version }}} If you have a patch to submit, do it through "JIRA":http://issues.apache.org/jira/browse/Buildr. We want to make sure Apache gets the right to use your contribution, and the JIRA upload form includes a simple contribution agreement. Lawyer not included. h2. Source Code Did we mention Buildr is an open source project? In fact, when you install Buildr you get all the source code, documentation, test case and everything you need to use it, extend it and patch it. Have a look in your Gem directory. But if you want to work with the latest and greatest, you'll want to check out "Buildr from SVN":http://svn.apache.org/repos/asf/incubator/buildr: {{{!sh $ svn co http://svn.apache.org/repos/asf/incubator/buildr/trunk buildr }}} You can also browse the "Buildr repository":http://svn.apache.org/repos/asf/incubator/buildr. Not a fan SVN? We understand. You can also grab a copy of "Buildr from Github":http://github.com/vic/buildr/tree/master: {{{!sh $ git clone git://github.com/vic/buildr.git }}} To install Buildr from the source directory: {{{!sh $ cd buildr $ rake setup install }}} When using Buildr for JRuby: {{{!sh $ cd buildr $ jruby -S rake setup install }}} h2. Testing/Specs Obviously we won't turn down patches, but we'll love you even more if you include a test case. One that will fail without the patch, and run successfully with it. If not for our love, then think of the benefit to you: once we add that test case, we won't accidentally break that feature in the next release. We test using "RSpec":http://rspec.info/, a Behavior-Driven Development test framework. The main difference between RSpec and xUnit is that RSpec helps you formulate test cases in terms of specifications: you describe how the code should behave, and run RSpec to make sure it matches that specification. You can run an individual specifications using the @spec@ command, for example: {{{!sh $ spec spec/compiler_spec.rb -l 409 }}} To make sure your change did not break anything else, you can run all the specifications (be patient, we have a lot of these): {{{!sh $ rake spec }}} We always @rake spec@ before making a release. You can also check out the "RSpec report":report.html and "test coverage report":coverage/index.html for the current version of Buildr. And if you want to help us on the journey to 100% test coverage, we'll be ever so grateful! h2. Documentation Yes, we do make typos, spelling errors and sometimes we write things that don't make sense, so if you find a documentation bug, or want to help make the documentation even better, here's the way to do it. For simple typos and quick fixes, just send a message to the mailing list or log an issue in JIRA. If you end up rewriting a significant piece of text, or add new documentation (your rock!), send a patch. Making documentation patches is fairly easy. All the documentation is generated from text files in the @doc/pages@ directory, so all you need to do is check it out from SVN, edit, and @svn diff@ to create a patch. We use "Textile":http://www.textism.com/tools/textile/ as the markup language, it takes all of a few minutes to learn, it's intuitive to use, and produces clean HTML. Also check out the "Textile Quick Reference":http://hobix.com/textile/quick.html. You can always check the documentation to see which conventions we use, and also a couple of extensions we have for styling source code (with syntax highlighting!) and handling footnotes. The table of contents is auto-generated form H1/H2 headers. The tool we use for this is called Docter, which we developed specifically for Buildr, and use to create the Web site and printable PDF. If you want to try it out you'll need to first @gem install docter@. To generate a copy of the Web site, simple run @rake html@ . If you're thinking of editing the docs, and using @rake html@ to see what the HTML looks like, you may want to try something simpler. Start by running the Docter Web server with @rake docter@ and then point your browser at @http://localhost:3000@. To see your edits, simply refresh the page. Generating the PDF is a bit more tricky, we use the HTML in combination with print media CSS stylesheets and run them through the wonderful "PrinceXML":http://www.princexml.com/, so you'll need to install PrinceXML first before you can @rake pdf@. h2. Contributors Here is the list of people who are actively working and committing on Buildr: *"Assaf Arkin":http://labnotes.org* (assaf at apache.org) *Alex Boisvert* *"Matthieu Riou":http://offthelip.org* *Victor Hugo Borja* (vborja at apache.org) Currently a Java Developer at "http://jwmsolutions.com":http://jwmsolutions.com, Victor has been enjoying and using Apache's software since 1999 when he started with Java, now he prefers programming Ruby and is happy to help on Apache's first ruby project.