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:

git config --global user.name "Mike Tester" 
git config --global user.email "mtester@gweezlebur.com" 

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”

$ git clone git://github.com/wycats/merb-core.git
Initialized empty Git repository in /tmp/merb-core/.git/
remote: Generating pack...
remote: Done counting 1684 objects.
remote: Deltifying 1684 objects...
remote:  100% (1684/1684) done
Indexing 1684 objects...
remote: Total 1684 (delta 800), reused 57 (delta 8)
 100% (1684/1684) done
Resolving 800 deltas...
 100% (800/800) done

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

$ git checkout -b my_bugfix 
Switched to a new branch "my_bugfix" 

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’.

$ git commit -a -v

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:

Created commit 14626c1: Added bug zapper library
 1 files changed, 2 insertions(+), 1 deletions(-)

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

$ git checkout master
$ git pull
$ git checkout my_bugfix
$ git rebase master
$ git format-patch master..
0001-Added-bug-zapper-library.patch
0002-initialize-zapper.patch

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

$ git rebase --continue

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.

$ git checkout master
Switched to branch "master" 

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

$ git branch -D my_bugfix
Deleted branch my_bugfix.

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:

$ git pull