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. 
