<commit_before>---
layout: default
title: Contributing
---

Buildr is a community effort, and we welcome all contributors.  Here's your chance to get involved and help your fellow developers.

h2(#involved).  Getting involved

All our discussions are done in the open, over "email":mailing_lists.html, and that would be the first place to look for answers, raise ideas, etc.  For bug reports, issues and patches, "see below":#bugs.


h2(#mailing_lists).  Mailing Lists

We run two mailing lists, the "users":http://buildr.markmail.org/search/list:users mailing list for developers working with Buildr, that would be you if you're using Buildr or interested in using it.  There's the "dev":http://buildr.markmail.org/search/list:dev mailing list for talking about development of Buildr itself. There's also "commits":http://buildr.markmail.org/search/list: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).  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:

{% highlight sh %}
$ ruby --version
$ buildr --version
$ java --version
{% endhighlight %}


h2(#wiki).  Community Wiki

Our community Wiki is available at "http://cwiki.apache.org/confluence/display/BUILDR/Index":http://cwiki.apache.org/confluence/display/BUILDR/Index.


h2(#code).  Contributing Code

Yes, please.

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.

h3.  The Perfect Patch

If you want to get your patch accepted quickly:

#  Provide a good summary of the bug/fix.  We use that to decide which issue we can do quickly, and also copy and paste it into the changelog.
#  Provide short explanation of what failed, under what conditions, why, and what else could be affected by the change (when relevant).  The helps us understand the problem and move on to the next step.
#  Provide a patch with relevant specs, or a fix to incomplete/broken specs. First thing we have to do is replicate the problem, before applying the change, and then make sure the change fixes that problem.  And we need to have those specs in there, they make sure we don't accidentally break it again in the future.
#  Provide a patch with the fix/change itself.  Keep it separate from the specs, so it's easy to apply them individually.

If you don't know how to fix it, but can at least write a spec for the correct behavior (which, obviously would fail), do just that.  A spec is preferred to a fix.

h3.  Working on a new feature?

If you want to work on a cool new feature, but not quite ready to submit a patch, there's still a way you can get the Buildr community involved.  We're experimenting with using Git for that.  You can use Git to maintain a fork of Buildr that can keep up with changes in the main branch (tip: use @git rebase@), while developing your own changes/features on it.

That way you can get other people involved, checking out the code, and eventually merge it back with the main branch.  Check out the "Git section":#git below and the post "Git forking for fun and profit":http://blog.labnotes.org/2008/04/30/git-forking-for-fun-and-profit/.


h2(#edge).  Living on the edge

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.

h3(#svn).  SVN

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/buildr:

{% highlight sh %}
$ svn co http://svn.apache.org/repos/asf/buildr/trunk buildr
{% endhighlight %}

You can also browse the "Buildr repository":http://svn.apache.org/repos/asf/buildr.

h3(#git).  Git

Not a fan SVN?  We understand.  You can also use the "official Apache Git clone.":http://git.apache.org  This clone is maintained by the ASF and kept in sync with the SVN repository (though, in practice there may be some delay in cloning recent commits).  Apache's Git hosting supports both git:// and http:// protocols (you should use git:// if at all possible as it is faster than http://):

{% highlight sh %}
$ git clone git://git.apache.org/buildr.git
# or...
$ git clone http://git.apache.org/buildr.git
{% endhighlight %}

If you want to learn more about Git, you can start by watching Scott Chacon’s "Git presentation":http://en.oreilly.com/rails2008/public/asset/attachment/2816 (PDF), or any of the "Git screencasts":http://www.gitcasts.com/.  For more, there's also the "Git Internals book":http://peepcode.com/products/git-internals-pdf.

And keep this "Git cheat sheet":http://ktown.kde.org/~zrusin/git/git-cheat-sheet-medium.png close at hand. Very useful.

h3. Working with Source Code<commit_msg>Typo fix.<commit_after>---
layout: default
title: Contributing
---

Buildr is a community effort, and we welcome all contributors.  Here's your chance to get involved and help your fellow developers.

h2(#involved).  Getting involved

All our discussions are done in the open, over "email":mailing_lists.html, and that would be the first place to look for answers, raise ideas, etc.  For bug reports, issues and patches, "see below":#bugs.


h2(#mailing_lists).  Mailing Lists

We run two mailing lists, the "users":http://buildr.markmail.org/search/list:users mailing list for developers working with Buildr, that would be you if you're using Buildr or interested in using it.  There's the "dev":http://buildr.markmail.org/search/list:dev mailing list for talking about development of Buildr itself. There's also "commits":http://buildr.markmail.org/search/list: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).  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:

{% highlight sh %}
$ ruby --version
$ buildr --version
$ java --version
{% endhighlight %}


h2(#wiki).  Community Wiki

Our community Wiki is available at "http://cwiki.apache.org/confluence/display/BUILDR/Index":http://cwiki.apache.org/confluence/display/BUILDR/Index.


h2(#code).  Contributing Code

Yes, please.

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.

h3.  The Perfect Patch

If you want to get your patch accepted quickly:

#  Provide a good summary of the bug/fix.  We use that to decide which issue we can do quickly, and also copy and paste it into the changelog.
#  Provide short explanation of what failed, under what conditions, why, and what else could be affected by the change (when relevant).  The helps us understand the problem and move on to the next step.
#  Provide a patch with relevant specs, or a fix to incomplete/broken specs. First thing we have to do is replicate the problem, before applying the change, and then make sure the change fixes that problem.  And we need to have those specs in there, they make sure we don't accidentally break it again in the future.
#  Provide a patch with the fix/change itself.  Keep it separate from the specs, so it's easy to apply them individually.

If you don't know how to fix it, but can at least write a spec for the correct behavior (which, obviously would fail), do just that.  A spec is preferred to a fix.

h3.  Working on a new feature?

If you want to work on a cool new feature, but not quite ready to submit a patch, there's still a way you can get the Buildr community involved.  We're experimenting with using Git for that.  You can use Git to maintain a fork of Buildr that can keep up with changes in the main branch (tip: use @git rebase@), while developing your own changes/features on it.

That way you can get other people involved, checking out the code, and eventually merge it back with the main branch.  Check out the "Git section":#git below and the post "Git forking for fun and profit":http://blog.labnotes.org/2008/04/30/git-forking-for-fun-and-profit/.


h2(#edge).  Living on the edge

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.

h3(#svn).  SVN

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/buildr:

{% highlight sh %}
$ svn co http://svn.apache.org/repos/asf/buildr/trunk buildr
{% endhighlight %}

You can also browse the "Buildr repository":http://svn.apache.org/repos/asf/buildr.

h3(#git).  Git

Not a fan of SVN?  We understand.  You can also use the "official Apache Git clone.":http://git.apache.org  This clone is maintained by the ASF and kept in sync with the SVN repository (though, in practice there may be some delay in cloning recent commits).  Apache's Git hosting supports both git:// and http:// protocols (you should use git:// if at all possible as it is faster than http://):

{% highlight sh %}
$ git clone git://git.apache.org/buildr.git
# or...
$ git clone http://git.apache.org/buildr.git
{% endhighlight %}

If you want to learn more about Git, you can start by watching S<NAME>’s "Git presentation":http://en.oreilly.com/rails2008/public/asset/attachment/2816 (PDF), or any of the "Git screencasts":http://www.gitcasts.com/.  For more, there's also the "Git Internals book":http://peepcode.com/products/git-internals-pdf.

And keep this "Git cheat sheet":http://ktown.kde.org/~zrusin/git/git-cheat-sheet-medium.png close at hand. Very useful.

h3. Working with Source Code
{'fraction_non_alphanumeric': 0.08080364976311634, 'fraction_numerical': 0.004737673276013336, 'mean_word_length': 3.9799038881607687, 'pattern_counts': {'":': 36, '<': 4, '<?xml version=': 0, '>': 4, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4086539', 'n_tokens_mistral': 3367, 'n_tokens_neox': 3156, 'n_words': 1644}