Getting Involved

<h1>Getting Involved</h1>

If you want to help make JRuby a better piece of software there are many 
ways you can help.  This document is divided into three areas:<p/>

<ol>
<li>Ruby coders</li>
<li>Java coders</li>
<li>Documenters</li>
</ol>

Most people interested in JRuby qualify for all three areas.  Please
consider each area as they are all important to the success of the project.</p>

<h2>Ruby Coders</h2>

As a Ruby coder you can help JRuby by finding areas where JRuby is not
behaving properly.  This generally involves trying to use JRuby in place
of Ruby and seeing if your software runs.  When you find something which
is behaving incorrectly (or not at all), then you should:</p>

<ol>
<li>Reduce the problem as small as you can.  Hopefully it ends up being
   a couple of line test case</li>
<li>See if you can find a bug report on jruby's sourceforge site</li>
<ul>
<li>If so, then you can comment on the bug if you think you have something 
     to add which may be helpful in correcting/diagnosing the problem.  
     Especially, if you have a better test case.</li>
<li>It not, then you should send an email to jruby-devel with the test case,
      and if helpful, what module you noticed the problem in.</li>
</ul>
<li>A Java developer will triage the problem and either</li>
  <ul>
  <li>Fix the problem</li>
  <li>Ask you to add a bug report</li>
  <li>May add the bug report themselves (they may have some insight that
       makes this a better choice)</li>
  </ul>
</ol>

<h2>Java Coders</h2>

As a Java code you contribute by fixing problems or missing functionality
in the JRuby implementation of Ruby.  Additionally, you can contribute time
to improving the java integration or embedding features of JRuby.  <p/>

The first thing you should do is create a working sandbox and make sure you can
compile and run JRuby.  See {getting a working sandbox} for more information
on this.<p/>

The next thing you should do is figure out what you want to work on.  Largely,
most frequent contributors generally contribute to itch their own scratch.
This means they want some ruby software to run and they have found problems 
that are impairing their progress.  What if you don't have any current 
itches?  We have plenty of tasks you can work on:<p/>

<ol>
<li>Any open bug on the sourceforge site is fair game</li>
<li>Any TODO/Fixme in the source may be fair game.  If the TODO is an obvious 
   error in Ruby behavior then you can just fix it.  If it is a refactoring 
   TODO which was written by someone who would like a section rewritten, then
   you should send a message to jruby-devel and inquire about the item.</li>
<li>Any missing native library in Ruby which JRuby does not have yet (e.g.
   zlib, socket, digest, etc...).  We are trying to write all these libraries
   in Ruby using Java integration.  You can look at digest.rb in our source
   distribution for an example of how this can work.</li>
<li>Try making a script to exercise a standard library in Ruby with JRuby.  For
   example, require matrix.rb and do some matrix operations and see if Ruby
   and JRuby match.</li>
<li>Try running against unit tests in Ruby source tests directory against 
   JRuby.</li>
<li>Look for missing methods in JRuby's implementation of core libraries.
   In some cases we have TODO's indicating these and in others we don't.
   The Pickaxe book is useful in this case.</li>
<li>Find something undesirable/missing about JRuby's java integration features 
   and propose something.</li>
<li>You can always ask the jruby-devel mailing list.  You may or may not
   get an answer depending on the winds direction.</li>
</ol>

When you do find something to work on, follow the following process:<p/>

<ol>
<li> Make sure no one is already working on your new found task.  To do 
     this:</li>
 <ul>
 <li>Look for bug report on JRuby's sourceforge bug list</li>
 <li>Send a message to jruby-devel saying what you are working on.  Someone
     may have input that can help you out.  Having a reduced test-case when
     possible is always desired to limit the scope of discussion.</li>
 </ul>
<li>Become a code monkey and fix the problem (or add the feature)</li>
<li>Add test case(s) in the tests directory to exercise the problem</li>
<li>Make sure you did not create any regressions</li>
 <ul>
 <li>via built-in unit tests</li>
 <li>via rubicon test suite</li>
 </ul>
<li>Generate a patch from the root of the project tree</li>
<li>Submit the patch to jruby-devel</li>
<li>pat your self on the back and find another thing to work on</li>
</ol>

After a trial period where we get used to your contributions, personality,
and general commitment (read this as you did not submit two patches and then 
quit the project), we will make you a full contributor.  <p/>

<h2>Documenters</h2>

JRubys documentation is sorely lacking.  Almost any idea for better 
documentation would be helpful.  Ideas for documentation include:<p/>

<ol>
<li>Introductory documents on topics like:</li>
  <ul>
  <li>Embedding JRuby into a Java application</li>
  <li>Example using JRuby's Java integration features</li>
  </ul>
<li>Better core API documentation:</li>
  <ul>
  <li>java integration features (low-level and high-level docs)</li>
  <li>BSF documentation</li>
  </ul>
<li>Example code with commentary</li>
</ul>