Thursday, May 14, 2009

Help JRuby by Fixing RubySpecs

A number of you have asked how you can help JRuby development. Well there's actually an easy way: fix RubySpec failures.

You may have noticed we periodically update our RubySpec "stable" revision number, and usually have to file a few bugs. This isn't because we don't want to fix those issues...on the contrary, we would love to fix them. We just don't have enough manpower, and there's usually harder issues we need to tackle first.

But most of the failures are easy to fix, and a lot of JRuby newcomers have gotten their feet wet fixing them. So here's a short guide on how to run the specs and fix them quickly.

1. Get a JRuby working copy and build it

This is as simple as 'git clone git://', then 'cd jruby' and 'ant'. You'll need Apache Ant 1.7 and Java 5/1.5 or higher (grab "Java SE Development Kit" from the Java SE downloads page.

2. Run the CI spec run

We have a clean spec run that should be clean for you before you start. Just run "ant spec-short" and it will pull the mspec and rubyspec repositories, roll them to the stable versions, and run all known good specs. Now you're ready to investigate specific failures.

3. Run specific spec files with bugs reported

You can look in Jira under the "RubySpec" category, or look under spec/tags/ruby for "tag" files listing failing specs and Jira bug numbers. Once you find something you'd like to investigate, run that spec file using "bin/jruby spec/mspec/bin/mspec <path/to/spec/file>". For example to set the Range#initialize failures I just reported, run "bin/jruby spec/mspec/bin/mspec spec/ruby/core/range/initialize_spec.rb".

Now you can proceed to fixing it.

4. Identify where the problem is.

Most of the core classes are pretty easy to locate. Any classes in the "core" specs will have a Java class named Ruby, like RubyArray, RubyRange, and so on. They're generally located in src/org/jruby. If you know any Java, these files are pretty easy to follow, and we're standing by on IRC or on the mailing list to hold your hand at the start.

5. Create a patch and submit it to the bug

Once you have a working fix, you can go ahead create a patch, either with "git diff > somefile.patch" or by committing it to your local repository and using "git format-patch -1" to create a formatted patch for the topmost commit. Some git-fu may be necessary, so I usually just use "git diff".

That's all there is to it! You'll be a JRuby contributor in no time!