If you read this blog, you obviously care about open source. If you’ve never contributed to an open source project, though, you might have some cold feet about it. So, inspired by the Ruby 1.9.3 Documentation Challenge, I wrote up a post for my blog about how to contribute documentation to Ruby. I got some feedback like this:
@steveklabnik Hey this is awesome. It's time for me to solider up and pitch in. Thanks for the added incentive!— Chris Baglieri (@chrisbaglieri) May 10, 2011
So I figured something more general might encourage you to get involved with whatever open source project you’re using, even if it’s not in Ruby. Every project can use a hand, especially the small ones.
A small aside about getting cold feet.
If you’re not contributing because you think you’re not ready, don’t worry about it! I know that this is easier said that done, but really, you’re ready. A friend of mine posted an article about why he doesn’t contribute, and I’m sure that many people share these kinds of fears. Greg Brown responded and addressed some of his concerns, but most of the people I’ve talked to object for two basic reasons:
- It’s too hard.
- I’m not good enough to contribute.
- I don’t have the time.
Let’s talk about each of these, in reverse order. It’s true, you may have a busy life. I don’t know your personal schedule. But I’m sure you could find a spare hour or two, maybe on a weekend? That’s all it takes to get started. Most projects are built on the backs of a thousand tiny commits. You don’t need to make a large contribution, even small ones are valuable.
If you have fears about the quality of your code, well, the only way you’ll get better is with practice. So fire up that editor, and submit a patch! Generally, if something isn’t quite right about your submission, there’ll be a discussion about it on GitHub, and everyone learns. Take this pull request, for example. Colin originally submitted a patch that linked to the wrong URL, wilkie mentioned this, and Colin updated his code. It’s going to get merged as soon as I stop writing posts for the Changelog. :) But, this is generally what happens if your first submission is a bit off the mark. Don’t be scared! This is how we all learned, from each other.
The “It’s too hard” complaint usually comes out of “I’m not good enough.” But it can also happen if you try to contribute to a large project, where there are a lot of rules. Contribution guidelines, code coverage requirements, updating AUTHORS and CHANGELOG files… big projects need to have process to manage the large number of contributors, but this can certainly create a barrier to entry for newcomers. If process intimidates you, I have a suggestion: start small! Smaller projects often have little to no process whatsoever. Plus, you’ll make someone feel incredibly good. Think about it: Python receives a bunch of patches every day, but if you had a little tool you wrote up on GitHub, and all of a sudden you got an email, “Hey, someone has a patch for you,” I bet you’d feel pretty good about it!
The absolute basics
When contributing to an open source project on GitHub, there’s a very basic workflow that almost every project follows. Three steps: Fork, commit, pull request.
GitHub makes the fork step really easy. Just click on the ‘fork’ button found on any project page. Let’s use Ruby as an example. The project page is here. You can see the fork button on the upper right. It looks like this:
Click that, and you’ll see some ‘hardcore forking action,’ and then you’ll be at your own fork! This is your own version of your project, and it appears on your GitHub page. For example, here’s my fork of Ruby. You’ll see a URL on that page, and that lets you clone the project down.
$ git clone firstname.lastname@example.org:steveklabnik/ruby.git
This creates a ‘ruby’ directory with all of the code in it. Next, let’s add a remote for upstream, so we can keep track of changes they make:
$ cd ruby $ git remote add upstream https://github.com/ruby/ruby.git $ git fetch upstream
Now at any time, we can grab all of the changes the main Ruby repository by doing a rebase:
$ git rebase upstream/master
A small note: ruby still uses both
svn as well as
git, so they call the master branch trunk. If you’re doing this for ruby, you’ll need
git rebase upstream/trunk.
Now that you’ve cloned, you can do you work! I like to work in feature branches, as it makes things nice and clean, and I can work on two features at once.
$ git checkout -b feature/super-cool-feature $ vim something $ git add something $ git commit -m "Fixed something in something"
Once you’ve got some commits that fix your problem, push them up to GitHub:
$ git push origin feature/super-cool-feature
And then you click the pull request button:
Select your branch, change the description of you want, and you’re good to go! The maintainer of the project will look it over, you might end up with a discussion, and you’ll soon get something accepted in somewhere!
What should I contribute to?
The best way to contribute is to help out with a project that you actually use. That way you’ll get to take advantage of the fruits of your labors. You’ll be more motivated, you already understand the project and what it does, and that’ll make it easier on you.
If you don’t want to or can’t figure out how to work on something you use, the next best way is to start using some new software! Keep reading the Changelog and pick a project that looks interesting, use it for a few weeks, and then contribute!
We’re all in this together.
I hope this encourages you to get your hands dirty, roll up your sleeves, and contribute. Even the smallest patch has worth, so please, make some time out in your schedule, pick a project, and give it a shot. You might just find yourself hooked.