Contributing to Laika

The most recent development documentation for Laika (based on CCHIT/laika) is always available at: rdoc.info/projects/CCHIT/laika. You can also generate the HTML docs yourself using YARD. See the README.

Development is managed using the Git source control system. A good source of information on Git usage is the GitHub guides: github.com/guides/home

For GitHub users:

The easiest way to get a patch reviewed and approved quickly is to fork from the main Laika repository on GitHub: github.com/CCHIT/laika

After you make your changes and push, you can send a pull request and your changes will be reviewed and possibly merged.

For everyone else:

$ git clone git://github.com/CCHIT/laika.git
$ cd laika
$ git checkout -b my_changes
$ <hack hack hack>
$ git commit -a
$ <maybe some more hacking>
$ git commit -a
$ git pull origin master
$ git merge master
$ git format-patch --stdout master > my_changes.patch

Send your patch to the developer list: dev@projectlaika.org

Running Tests

If the tests do not pass with your patch applied it will be rejected. Make sure the tests pass before you submit any changes.

Environment

Laika uses Saxon (saxon.sourceforge.net/) to handle XML Schema validation and XSLT. For this to function properly, the Saxon jars must be set in a CLASSPATH environment variable.

Navigate to the root of your Laika project and run:

$ source bin/laika_env.sh

As an alternative, you may create CLASSPATH environment variable as part of the user's profile.

Running Individual Specs

Sometimes it's more convenient to run individual spec files:

$ jruby -S spec <specfile>

Remember to run the entire suite before pushing any changes:

$ jruby -S rake spec

RCov Test Coverage

It's possible to get RCov working in jruby:

$ git clone git://github.com/spicycode/rcov.git
$ cd rcov
$ jruby setup.rb config
$ jruby setup.rb setup
$ jruby setup.rb install
$ cd <laika_project_dir>
$ jruby -S rake spec:rcov

ruby-debug

If you want to be able to use the ruby-debug command line debugger, you will need to install a base gem which has the native extensions compiled, because JRuby cannot perform this step.

NOTE: Check for the latest versions of ruby-debug-base.

$ wget http://rubyforge.org/frs/download.php/48904/ruby-debug-base-0.10.3.1-java.gem
$ jruby -S gem install -l ruby-debug-base-0.10.3.1-java.gem
$ jruby -S gem install --ignore-dependencies ruby-debug

Then add a line calling 'debugger' in your test code at the point you want to break out and:

$ jruby --debug code-to-test.rb

Will drop you into the debugger.

For more information on installation see:

debug-commons.rubyforge.org/#jruby-debug