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.
