How do you choose an open source project to contribute to?
Think of it this way: You're looking for a project whose goal and community would make for an engaging hobby. (Even if you only contribute to the project once, it should still be something you enjoy doing.)
There is one exception: If you have to work on this project for your job or a similar reason.
Think about the following things:
Before you contribute to an open source project, you're going to want to be familiar with how the program works and what people use it for. Legend has it that the best projects to contribute to are ones you already use. What matters most is that you can understand what kinds of changes would benefit users of the program, and that comes from experience using it.
Many open source projects have one set of information for users of the project, and another set of information for prospective contributors. It's essential that you find the contributor-oriented venues so you can be plugged into conversation about the project.
Look for these kinds of things:
The documentation for some open source projects is very scattered, so your best bet for finding (for example) the WordPress email list is to just search the web with Google. Try searching for [wordpress email list].
Note that if a project does not use tools like this, that can be a warning sign that they are not good at handling contributions.
This step is essential, so raise your hand when you finish, and a staff member will come by, validate your findings, and give you a high-five.
For this step, you can come up with your own idea, or find a task suggested by the project.
We strongly recommend choosing a task that is very well-defined! Fixing a typo in the documentation, adding some comments to the project's source code, or fixing a small bug with a very clear solution are all good options.
Many projects list bugs that are "easy", or good for first time contributors. A future version of this document will link to good first bugs.
If you have come up with your own idea of what to work on, make sure to enter it into the bug tracker for the project.
Once you have your idea of what you'll work on, raise your hand, and a staff member will come by and make sure they agree it will fit in the limited time we have today. Then you will get a high five!
Open source projects usually keep the latest version of their source code in some sort of version control system. In this step, you should find out where the source code is kept and download it onto your computer.
(Note that different projects have different ways of storing their source code, so this part can get somewhat complex.)
If the project is hosted on Github, you should log into Github and click "fork", then use "git" on your computer to "clone" your new personal copy of the project.
Generally, look for instructions by the project for a "clone" or "checkout" command.
Finally, you should know there are a couple of exceptions. First, some projects accept translations via a website, in which case there is nothing to download! That's easy. Second, a small number of projects do not use version control tools. Instead, they periodically release "tarballs." In that case, you'll need to download and extract the "tar" file for the latest version of the software.
Finding the right way to get the code can be difficult, so feel very welcome to raise your hand and ask for help. Once you have this download started, raise your hand, and a staff member will come by and verify. Once you and the staffer agree, you get a high five!
This varies wildly from project to project. Once you download the code, look for a README or INSTALLATION file to see how to set it up.
In the case of a web application, like WordPress, you will need to run a web server on your own computer.
In all cases, you'll need to use a plain text editor:
Note that if you are making changes such as translation that can be done entirely via the web, all you have to do to satisfy this step is to visit the appropriate website!
Once you have a working development environment for your project, you should raise your hand and show it to a staff member. Congratulations! This is often the hardest part of contributing to a project.
Whatever problem you are trying to solve, make sure you understand exactly what the problem is.
We recommend trying to reproduce the problem yourself. For example, if you are trying to solve a bug where, upon printing, the document comes out all red, try it. That way, you'll be able to tell if your changes fix the problem.
You might even find the bug can't be reproduced, in which case you should say so on the bug tracker. (Perhaps the bug is actually fixed, in which case, congratulations! You don't have to write any code; you just have to update the status of the bug, and then you get credit!)
If you can't figure out how to reproduce the problem, raise your hand and ask an instructor for help.
Once you can reproduce the problem, raise your hand, and discuss the bug with an instructor. Once the staff member verifies you've reproduced the problem, you earn a high five!
Look at the code, try to figure out which parts are relevant to the bug. Note that these may be in different files!
Change the code in small steps, each time checking the behaviour of the modified program. This way you will understand which part of code controls which behavior.
At some point, you will get the desired result, or at least something that looks like it. Now it's time to move on to the next step.
If there is an automated test suite, check that the program still passes all the tests. If not, you have broken something: go back one step and fix it!
Check that the program has the desired behavior; if there is a test suite add your tests to it. Do not forget corner cases! Be nasty with your program: it's a good way to avoid to discover bugs later!
Once a program passes all the tests, it is time to send it out in the world.
Check what you changed. With git, there are multiple ways of doing it, all of them a bit different:
If your project does not use git, there should be equivalent commands.
Don't forget to make your changes as small as possible! This makes it easier (and more precise!) to go back on your steps later.
Feeling insecure? Now it's a good time to ask feedback! Ask someone in person, if you are at an event; or ask on IRC or on the mailing list of the project!
Add your changes to be committed. With git, the process is quite straightforward:
Now, with git commit -m "A short message describing your changes" you commit your changes. If you want to add a longer message, you should use git commit: this may send you to a text editor (usually Vim) where you can write a short (less than 50 characters) title for your commit followed by a more detailed description. The basics commands you need for Vim are:
If you are certain you want to commit all the files you changed, you can use git commit -a (or git commit -a -m if you want to add a short message).
Some projects prefer that you send a pull request, others prefer that you format a patch and attach it to a bug description. Check the page of the project.
You may have to discuss your solution of the bug with the maintainer of the project. Be open-minded (and nice)!
In case you change something, don't forget to go back and test! In fact, you will have to repeat all the steps that follow after editing.
Celebrate! And then move on to next bug... or find a project you want to implement!
