Refactotum Overview

The Refactotum Project has two objectives:

  1. Show developers how to contribute to open source projects.
  2. Encourage healthy code through refactoring

To perform a refactotum exercise, you need to set aside four hours, and perform the following steps:

The four-hour timebox is very important. The number one enemy of contributing to open source is inertia. (You are fighting that battle by reading this.) The number two enemy is overambition. Start small.

Selecting an open source project

Start by selecting an open source project. You do not necessarily have to know much about the project, but you do need to know the programming language the code is written in! We will give examples written in Ruby, but the ideas are general and can be used with any language.

Here are some Ruby projects that are easy to get started with:

Download the project and run the tests

The next step is to download the project and run the tests. Most projects will give you at least three different options:

  1. Download a compressed dump of the project source
  2. Anonymous source control checkout (no commit access)
  3. Developer source control (commit access)

You will want the anomymous source control checkout. Having a source control checkout should guarantee that you are working on the latest, greatest code. Since you are contributing to this project for the first time, commit access is not an option. (You have to earn that.)

To get the repository

Many Rails applications rely on implicit loading of gems, so you may find that you don't have all the gems you need to run the tests. If you see a message of the form

no such file to load -- foo

your best bet is to gem install foo.

Find a bite-sized problem to solve

Pick something small and simple. You'll be amazed at how quickly a small change grows into something more ambitious. Here are some easy ways to brainstorm ideas for a Rails application.

Spec and implement your solution

Write specs, or tests, that demonstrate the code you plan to write. Then write the code to pass the tests. Look at the other tests in the project and follow their lead.

Create and submit a patch

Most open source projects welcome well-organized patches. (If they don't, fork 'em.) Make sure you make it easy for a busy maintainer to understand your patch.

Most importantly, read the project instructions for contributors, and follow them. Here are a few examples:

Pitfalls

There are several ways to stumble during your first open source contribution. Keep an eye out for these warning signs:

Let us know how it goes. Happy refactoring!