Friday, February 01, 2008

Contributing to Merb (Part 1)

I’ve seen several people ask “How can I help with merb-core?” and so, here’s a little guide. (Updated 2/14 w/ notes on rebasing. Thanks ReinH.)

This is part 1 of 2, for people who don’t want to run their own public fork.

Step 1: Get a Lighthouse account

All of the Merb development is moving to Lighthouse instead of Trac, so you’re going to need an account. Go register and then come back here.

Step 2: Get git

Merb is using git for development now. There’s information on the main git site about downloading and installing. There’s also some guides for installing on Mac. Google is your friend.

You should also configure git with your email address:

Liquid error: No such file or directory – posix_spawnp

These are global config settings that will apply to every project you checkout.

Step 3: Get Merb

Using git is different from using SVN. Every repository, whether published or not, is on equal footing with every other one. All of the official Merb releases will be coming out of wycats’ repository, though, so you probably want to get that one. Do that with “git clone”

Liquid error: No such file or directory – posix_spawnp

This will create a new repository in the directory merb-core, set up the remote repository links, fetch the latest copy of the upstream repository into your repository. and set up a tracking branch for upstream.

Step 4: Fix something

This is the whole point, right? There’s a bug you’re dying to fix, or a feature you’re dying to add. So let’s do that. First, we create what git users calls a “topic branch” to hold the changes for this particular bug

Liquid error: No such file or directory – posix_spawnp

This creates the branch, and switches us to it. Now change whatever needs changing, of course running the specs to make sure they still pass.

There’s a lot of git commands you may use here that are beyond the scope of this guide, like diff and status. Consult your favorite git tutorial.

Now we need to commit the changes. Remember, in git every repository is equal, so you’re committing to your local repo, not trying to commit to wycats’.

Liquid error: No such file or directory – posix_spawnp

This will pop open an editor for us to type a commit message. It should have a short, very descriptive first line, a blank line, then any other information that’s relevant.


Added bug zapper library

This loads in the bugzapper library,
which removes some common bugs,
like the ones in ticket #343.

Save and quit, and you’ll see something like this:

Liquid error: No such file or directory – posix_spawnp

The important bit is “14626c1” … it’s the first part of the unique identifier for this commit. If you ever need to refer to this exact commit, you’ll need that.

However, since we used a topic branch, we know that every commit on this branch is part of the intended changes. So we can use a shorthand to actually generate our patch(es). First, though, let’s make sure we’re current with upstream

Liquid error: No such file or directory – posix_spawnp

This says “make patch files for every commit that is in this branch and not in master” (master is the default branch you started with). You can see that I committed another fix, so there are 2 patches.

If the rebase fails, it means your patches don’t apply cleanly with the latest upstream changes. You’ll have to fix that (either manually or using git merge-tool), and then

Liquid error: No such file or directory – posix_spawnp

After that, continue with formatting the patch.

Step 5: Submit the patche(es)

Go to Lighthouse. Create a ticket. Tag it with “patch”. Attach your patch(es). Wait for them to be applied.

Step 6: Cleanup

You should switch back to the master branch now.

Liquid error: No such file or directory – posix_spawnp

If your patches have been accepted, you can delete your branch, too:

Liquid error: No such file or directory – posix_spawnp

Branches are cheap, so you can leave it around for a while, if you think you might come back to it.

You should also pull down the latest changes, so your next patch will apply cleanly:

Liquid error: No such file or directory – posix_spawnp

Discussion

Follow me on Twitter. I don't have comments enabled, because I remember when we didn't have blog comments, and we did just fine, thank you very much.