UPDATE: I've updated the vagrant branch used below to support the newest version of Vagrant.

This is more substantial version of the lightning talk I gave at LA RubyConf last Saturday. If you're a Vagrant user already, this will be familiar. If not, don't worry, you're about to get a quick introduction to its power as a tool for web development. If you have any questions feel free to comment or find me on twitter @johnbender.


jQuery Mobile is set up to use php for serving the docs and tests, both of which you will need in order to start hacking on the library. Instead of installing apache and mod_php on your workstation though, we're going to build a vm using Vagrant that will serve it up.

First you'll need to install VirtualBox and Vagrant which is covered in glorious detail by Mitchell's documentation. If you're questioning the time investment at this point I can promise you that its worth it. Vagrant will change the way you look at web development.

Clone and build

The next step is to fork and clone the jQuery Mobile repo

$ git clone [email protected]:yourgithandle/jquery-mobile.git
$ cd jquery-mobile

add my fork as a remote

$ git remote add geewilikers

track the branch with the Vagrant configuration

$ git fetch geewilikers
$ git branch --track vagrant geewilikers/vagrant
$ git checkout vagrant

make sure to add a base box from which to build our JQM virtual machine

$ vagrant box add base

and then fire that sucker up!

$ vagrant up

About 2 to 5 minutes later, depending on your connection speed, you should be able to hit the docs site served by your brand new vm. You can also view some tests.

Making changes

So now that the site is running how do you make changes? What do you do with this new branch? What does the workflow look like?

Its actually quite simple. Vagrant lifts the project directory into the virtual machine as a "shared folder" ( it actually mounts the folder with NFS because VirtualBox's shared folders have extremely poor performance for complex file structures ). This means you can edit any files you like locally and the changes will be represented immediately in the vm. Just make sure that you checkout master first and use the vagrant branch any time you want to run a vagrant command.

For example, if you wanted to fix a typo in the docs and had just finished building the vm:

$ git branch
* vagrant
$ git checkout master
... hack hack ...
$ git add .
$ git commit -m "changed the docs to be more awesome"

There's no need to stay on the vagrant branch, its only necessary when you want to interact with vagrant. For example if you wanted to suspend the vm after finishing some work:

$ git checkout vagrant
$ vagrant suspend

When you want to start working again, just resume the suspended vm:

$ vagrant resume
$ git checkout master

And that pretty much covers the workflow. If you ever want to go rooting around in the vm itself, which in this case I find to be a rare occurrence, you can simply ssh in:

$ vagrant ssh

In the worst case where your vm just doesn't seem to be working at all, just destroy it and rebuild it from scratch.

$ vagrant destroy
$ vagrant up

Pull requests

Now that its dead easy to make changes to JQM and you're ready to dive in and help out, where's the best place to start?

As of this writing the team is focusing on bug fixes and testing. Feature requests are being moved to a backlog for post beta/1.0 consideration as we focus on platform support and stability. That means if you want to contribute your best bet is to find an unclaimed issue ( ie one that isn't tagged with a person's name ), in the issues list on github and try your hand at a fix.

Once you're happy with your solution submit a pull request and ... wait. We're doing our best to get to all the pull requests but we get a fair amount and you might have to wait a couple days to get a response while we sort through them.

To speed the process along there are a couple important things you can do:

1. Rebase!

If/When your pull request branch falls behind master don't merge - rebase! By rebasing and resolving the conflicts you make the application of your commits to the existing master much easier for the reviewer.

First thing you'll want to do is add the original git repo

$ git remote add jqm git://

Then you can fetch the latest from the original jqm and rebase your changes on top of it

$ git fetch jqm
$ git branch
* master
$ git rebase jqm/master
... resolve conflicts ...

2. Separate white space/refactor commits

If you want to add in a quick refactor, like renaming a variable, or cleaning up some white space keep it in a seperate commit from the bug fix/feature. That way the reviewer doesn't have to fight to separate the important changes from the rest.

3. Test

This really cannot be over emphasized. If you fix a bug please add a test for it. In this way we can guarantee that there aren't any regressions in the future as the project makes changes and improvements. Just take a gander at the other tests to see what they should look like and dive right in. Even better, if you want to learn the library, just start writing tests for whats already there, you'll be making a huge contribution to the stability of the code base.

Contributing to other projects

The most important part of all, which I didn't get enough time to talk about at the conference, is that you don't have to be a rocket scientist or hacker extraordinaire to contribute in a big way to an open source project you're interested in. How do I know this, you may ask? Because I'm neither one of those things.

Sadly, I spent a lot of time on the outside looking in, thinking "I'd just be making trouble" or "I doubt I'd have any meaningful impact even if they did accept my submission". If you tend to think on the same level, stop. Go fix a bug. Go write a test. Don't let the fear of someone rejecting your submission stop you from trying in the first place.

Even if it doesn't get accpeted, take the feedback to heart, get better, and try again. Good projects will have a polite and helpful response for you if they don't think your fix is quite ready to be merged in. As someone who reviews pull requests I know that the most important asset the project has is its contributors and users. I see it as my most important job to make sure they know we appreciate all their hard work. ( credit to Yehuda Katz's talk, and many discussions with Mitchell Hashimoto for those ideals).

Dive right in

Hopefully if you were on the fence about contributing to JQM or any other oss project this was the nudge you needed to give it a try. Open source is dead if people don't jump in to contribute and make it better, so I hope to see your pull request in our queue sometime soon!


08 Feb 2011