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:
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 git@github.com: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.