Five tips for contributing to Rails

Tip One – Test ActiveRecord tests with different database types

When creating a patch for ActiveRecord you need to make sure your patch works with different databases. I learned this the hard way when I submitted a patch that worked perfectly in mysql and broke in every other database type.

If you have the database management system set up correctly and also added the required databases (activerecord_unittest and activerecord_unittest2) then you can run the following rake task in the rails/activerecord folder:

  $ rake test_[database type]

Where [database type] is the database system you’re looking to run the tests on.

For example:

  $ rake test_mysql
  $ rake test_sqlite
  $ rake test_postgresql

You can also use this rake task to run a specific ActiveRecord test.

For example, to run the base_test.rb tests using mysql:

  $ rake test_mysql TEST=test/cases/base_test.rb

Tip Two – Run ActionPack tests in TextMate

When I’m working on a Rails application I get pretty addicted to running tests in TextMate with Command-R. I found when working on Rails patches that it wasn’t quite so tidy.

ActionPack tests typically have require ‘abstract_unit’ at the beginning of the file.

At the top of the test file add:

$: << ".."

An explanation of what these strange hieroglyphs mean:

• $: is the search path (you can think of it as being an array of directory path names)
• ”..” the parent folder – you could have ’../tests/blahblah’ etc if you wanted to
• << pushes an element onto an array

And now it finds ‘abstract_unit’ in the parent folder, allowing the tests to run within TextMate – hooray!

Obviously, if abstract_unit isn’t in the parent folder, then you should adjust this to search in the right folder for abstract_unit. For example:

$: << "../tests/helpers"

Tip Three – ActiveRecord script/console

Anyone who’s spent anytime working on an ActiveRecord Rails patch will realise that the included test models can get pretty complicated. That’s why I like to create a special IRB console for playing around with the relationships.

• Download this file: script_console_for_rails.zip and unzip it into your rails/activerecord/ folder.
• Still in the activerecord folder run:

    $ script/console

<li>This opens a special <span class="caps">IRB</span> console that includes all the Rails test models and fixtures &#8211; allowing for cool stuff like this:</li>



• You can open it with different database types like this:

    $ script/console sqlite3
    $ script/console postgresql
    etc

Tip Four – Go through old unloved patches and fix them up

Stuck for ideas on how you can contribute to Rails? One great way is by going through old Rails patches in Trac and bring them up to speed.

Some patches work fine, but haven’t been accepted for a number of reasons:

• They need documentation
• They need tests
• The code that the patch applies to has been changed

This link provides a list of patches that are untested, undocumented and incomplete.

Or you could just browse through the old open bugs here for patches that work but need some attention.

Tip Five – Validate other peoples patches

Last year, the Rails Core team made a decision that patches need to be verified by three other contributors before being considered for acceptance. With this arrangement, the Core team now no longer have to waste their time examining half-finished patches, and the quality of patches are higher.

Verifying a patch is more than just agreeing with the idea, it requires a bit of effort.

Here’s the steps you need to take to verify a patch:

• Find a patch that needs verifying.

This bit’s easy. Just waltz on into #rails-contrib on freenode and ask “anyone want me to +1 their patch?” and prepare to be bombarded with requests.

• Agree with what the patch does

This may seem obvious, but there’s no need to verify a patch if you don’t believe that the patch belongs in Rails.

• Look at the source code

Give the code an eyeball in trac before downloading it. Make sure that the patch includes appropriate tests and documentation, and the code doesn’t have any glaring peculiarities. If it’s lacking in one of these areas post a comment on the ticket so that the contributor can make the necessary fixes.

If however you’re happy with how the patch looks then it’s time to take it for a test drive.

• Update your own Rails repository

This is so that when you install the patch you can be sure that it patches cleanly. If it doesn’t then post a comment on the trac ticket letting the contributor know so they can fix it.

If you’re using subversion then run

    svn update

• Download the patch

Sometimes trac tickets have multiple patch files, so make sure you’ve got the right one(s).

• Install the patch

Now install the patch on your own repository using a command like:

    $ patch -p0 -i [patch_file.diff]

(Replace [patch_file.diff] with the file path of the patch you want to apply.)

If the patch doesn’t apply cleanly you’ll get a message like:

    Hunk #2 FAILED at 738.

This is a sign that the code base has changed since the patch was created. The contributor will need to update the patch. Make sure you post a comment on the ticket with the details.

• Run the tests to make sure they all pass

    $ rake test

• Try out the patch with a test Rails application.

I like to keep my Rails repository in the vendor folder of a dummy application that for testing patches.

• Verify

If the patch works, and there are no obvious side effects, then you can +1 the trac ticket. Simply post a comment on the ticket with something along the lines of:

    +1 tests pass

If you find that you’re the third person to verify a patch, then add the verified keyword. This signals to the core team that this patch is ready for examination.

• Revert the patch

Run something like

    svn revert . -R

To ensure that the patch is no longer applied to your repository.