Starting from scratch on a new open source project can be confusing– especially if you’ve never contributed to open source before. On the Open Source Team, we go through the same process for each new project that we work on. Although every project is different, the general steps to take in order to contribute code are basically the same for all projects.
1. Pick a project
Easier said than done! Usually, the best projects for beginners are ones that are well-documented and have few dependencies. You also need to ensure your system meets the minimum requirements. Good places to find projects include: GitHub, SourceForge, Google Code
2. Locate development resources
Well-documented projects will have information for new developers in a wiki, README.txt file, or somewhere on the project’s website. At the minimum, you need to find the system requirements, project dependencies, how to compile, how to run, and location of the project’s source code repository. Ideally, there will be some community-related links, such as a forum, mailing list, chatroom (irc), etc.
If the development documentation is seriously lacking (and you can’t find info for the project anywhere else on the web), you could try your luck at reading the project’s source code yourself, or you might just have to give up hope entirely and go back to step #1.
3. Install dependencies
Most projects have them. Dependencies are libraries of code that the project depends on. It won’t work without them. Ideally, dependencies can be installed using a package management system such as Linux’s Advanced Packaging Tool (apt). If you don’t know what your project’s dependencies are or how to install them, go back to step #2.
4. Get the source from the repository
This includes the development source code AND version control data. It is different from what you get if you just click “download” (or whatever) on the project’s home page. You will need to know what kind of version control system the project is using (Git, Subversion, Mercurial, CVS, etc.) and install that system so that you can make a copy of the source code directly from the project’s repository. In order to do so, you’ll need to learn the basics of that particular version control system. If you don’t know where the project’s repository is, go back to step #2.
This is the most challenging part. You should not expect this to work right on your first try. If the project is popular enough, you should be able to just copy/paste your error into a search engine and find help. Try putting the core of the error into quotes when you search. Try searching the project’s community resources (forum, mailing list, etc). If you have to, send a message to the project maintainer asking for help… but no matter what: don’t give up! It is not unusual to spend hours trying to get a troublesome project to compile.
If you don’t know how to compile the project, go back to step #2.
6. Run it
Again, expect errors to occur. Use the same resources as from the last step in resolving them. Once you iron the errors out, then it’s time to celebrate: Congratulations, you just compiled and ran the project from the source code! Let the fun begin.
If you don’t know how to run the project, go back to step #2.
7. Run the test suite
Assuming the project contains one (which not all projects do), you’ll want to familiarize yourself with the test suite included in the project. The best way to do that is to try running the tests.
A test suite is a collection of individual automated test cases which are written to ensure that the code being tested works as expected. Tests are integral to well-developed projects as they prevent new changes from breaking previously working code. Can you imagine manually re-testing all aspects of an entire project after each and every change? Forget that!
Eventually, you’ll want to learn how to write tests for your own code– in fact, many projects will require you to do so in order to submit your changes anyways.
If you don’t know how to run the test suite, go back to step #2.
8. Pick an issue
This means finding the most up-to-date list of bugs and enhancements requests. Sometimes this will be in the README.txt file, or there might just be TODO comments scattered across the code-base. Ideally, the project is using some sort of web-based issue tracking system that lets anyone submit bugs. If it is possible to assign yourself to the bug, then do so before you start working on it. That way, someone else won’t swoop in and fix it before you do. The best issues for beginners are usually UI-based– not core functionality.
“But how do I find the file(s) relevant to my issue?” Use an editor that allows you to easily search the text of all files and folders in the project directory. I suggest the “Find in Files…” feature of Sublime Text 2. Once you’ve found the files to edit, just get in there are start hacking. You can’t learn without allowing yourself to fail.
Ideally, the tests in the test suite will serve as a good example of how to utilize various components of the project. Well developed projects will run the test suite automatically when you recompile. If not, then re-run the tests manually before moving on to the next step. You don’t want to break anything, after all!
10. Contribute your changes
The way you do this will depend on the project’s contribution guidelines and version control system. Once you’ve submitted your changes, then you must wait for a response from the project maintainer. Expect them not to like your code and reject it. Why?!? Because: You have no idea what you are doing! Don’t get your feelings hurt and give up– it happens to everyone. If the maintainer is nice, then they will make suggestions on how you can improve your contribution so that they will accept it. If they are mean, then you can either put up with it or give them the digital middle finger and start over at step #1.
And that’s it! Good luck finding your way in the world of open source!