Contributing to Merb (Part 2)

In Part 1 I talked about how to use git to work on the merb-core/merb-more projects that will be Merb 0.9.

This time I’ll show you a different workflow, for people who plan to make a lot of changes, or want to do something interesting and maintain it as a public fork.

Forking is sometimes a bad word, but no more! In this new gitastic world, forking is a cool thing. That’s why Github makes it so easy to do! When you fork, you do the same thing as when you clone….you just make your clone accessible to the world.

Step 1: Fork

Every Github project has a prominent “Fork” button, if you’re logged in.

So the first step is to click that button. As simple as that, you’ve made your own repository based on the original. You can add other people to it, accept patches, whatever you like. (In fact, I really hope someone will fork merb-core and merb-more, declare themselves to be the coordinator of documentation patches, and periodically feed those back to the main repos)

Play around with the settings. You can’t break it, and if you do, you can delete it and start over. Forks are cheap.

Step 2: Clone your new repo

Instead of cloning wycats’ repo, you want to clone your own. For instance, I have my own merb-core for experimental stuff, or if I want to give someone commit for a while to work on something together. When I clone my repo, I use the following:

$ mv merb-core merb-core-official
$ git clone git@github.com:ivey/merb-core.git

(This is not completely true. I have a much more complicated setup, which I may detail in Part 3)

Now, you probably want a way to keep in sync with the official repo. So let’s add it, too:

$ git remote add official git://github.com/wycats/merb-core.git

Now, anytime you want to sync up, you can use either of the following:

$ git pull official master
$ # or
$ git fetch official
$ git rebase official/master

The first version does an automatic commit of the merge, the second doesn’t.

Step 3: Fix stuff

This is where it gets fun. This is your repo. Make some changes. Use ‘git push’ to push them up to your github repo. Share them with #merb. Get people to run your version and try the changes out. Fix bugs.

If you’re hoping to get your changes merged back in, it’s a good idea to communicate with us about what you’re doing.

If you’re working on multiple big projects, it’s a really good idea to keep each one in a separate remote branch, so we can merge one without merging all of them. We can cherry-pick if needed, but it’s easier if you use branches.

$ git checkout -b feature1      # create a branch
# make changes
$ git commit
$ git push origin feature1      # push feature1 to remote

Or, you can git push —tags and push all of your local tags to your remote repo. Hey, it’s your repo, use it how you like.

Step 4: Getting changes merged

Now you need to get someone to merge your changes. Ideally, you’ll already have an open ticket in Lighthouse, have been in communication with folks in #merb, and maybe even have talked to one of the core devs about your changes.

   Hey, I have this fixed in my repo.

   Please pull:

   git pull git://github.com/jimmyhoffa/merb-core.git feature1

The important things to note are that you use your repo URL, you make it easy to copy/paste directly (starting it with ‘git pull’) and that you include the remote branch, even if it is master.

(Github will soon be adding a “Pull Request” button, so you can notify about patches via Github. Keep an eye out for that.)

If your changes are accepted, you’ll see your commits show up in the main repo and there will be much adulation. Hooray! This doesn’t even begin to scratch the surface of how awesome git is, but it should get you going. Oh, and if you’re like me, you’re dying to know how git works on the inside