The Beginner’s Guide to Contributing to Open Source Projects

Open source works by having many people contribute to the creation and maintenance of software. Thing is, it works well only when people are actually contributing.

The recently publicized Heartbleed bug in OpenSSL is a perfect example. The flaw was introduced by one programmer, contributing to a project with only four programmers, none of them who had OpenSSL as a full-time job. Nobody caught the bug until two years after it was in the wild. After all, Linus’ Law that “given enough eyeballs, all bugs are shallow” relies on there being enough eyeballs.

For many programmers, though, the thought of contributing to open source projects seems too difficult and time-consuming. They think that you have to be a programming genius blessed with unlimited free time to make a meaningful contribution.

That’s simply not true. Successful open source projects thrive on a wide variety of contributions from people with all levels of coding skills and commitment. If just one person fixes a compiler warning, closes a bug, or adds to the documentation, pretty soon you’re talking real progress.

open source signFor many people, the hardest part is just getting started. So here are some suggested ways you can begin contributing right away, at whatever level is most comfortable for you.

1. Report a bug

Bug/issue management is one of the least sexy ways to contribute to an open source project, but it’s also one of the most important.

When you find a bug in an open source package you use, report it into the project’s bug tracking system. This is probably the single most useful thing you can do to contribute to a project, because if users don’t report bugs, chances are that the developers won’t find about them. If the developers knew about the bugs, they would have fixed them, right? If you really want to help, take the time to do a good solid write-up into the project’s bug tracking system.

2. Verify and track down a reported bug

You can also go through the bug tracking system and help improve existing trouble tickets. Find a bug and see if you can reproduce it on your system. This can be invaluable to the developers trying to narrow down the cause of a problem.

Say you’re running version 1.4 of the imaginary FooCalc package under Mac OS X, and you see a bug in the bug tracker that was originally reported on version 1.3 on Linux. Try to reproduce the bug on your system, and report the results in the bug tracking system.

Checking for bugs on different operating systems can be especially useful to the project maintainers. For example, I maintain the search tool ack but have no access to Windows development environments, so I rely entirely on Windows-based users to help me diagnose and fix problems on that operating system.

3. Write an example for the documentation

Few developers are eager to write documentation, but it’s critical to the success of open source projects. What’s the first thing you look for when exploring a new project? The documentation. And what’s the first thing you look for in that documentation? Examples of how to use it.

It’s easy to come up with examples for the documentation if you’ve been using the software for a while. For projects related to programming, such as a library or a framework, create a simple example that shows a common use case of the code. In many cases, you can take working code of your own, extract the most interesting parts, and you have a real-world example to help new users understand quickly.

For applications, a few screenshots of common usage of the tool will go a long way to help new users.

4. Edit the project wiki

Wikis are becoming more and more prevalent as an easy way for people to contribute to project documentation. For some projects, like the Solr search engine, the project doesn’t have standalone documentation, leaving the wiki as the primary source of documentation.

The beauty of wikis is that there’s no minimum barrier to entry, so it’s easy to make contributions with a minimum of fuss. Adding a sentence here, a paragraph there takes only minutes but becomes part of the project forever, helping untold numbers of users down the line.

5. Answer a question

Time spent helping others is an investment in the project as much as writing code. The more qualified users of the software that join in helps grow the project as a whole. If you’re at all experienced with a given piece of open source software, you’re probably able to help people who are newer to it than you are. Try to lend a hand to others who are struggling.

A great place to start is StackOverflow, which has become the preeminent Q&A site for programmers helping other programmers. If your expertise runs more toward server administration, SO’s sister site ServerFault is a great place to help contribute your knowledge.

Of course, many projects have their own dedicated forums and mailing lists devoted. Sign up for one and see how you can help. Remember, the newbie you help today may someday contribute great new features.

6. Blog about your experiences

If you’ve ever tried to debug a frustrating problem with a piece of software, you’ve probably gone to Google to find the answer. Google doesn’t know the answer, of course. It can only point you to web pages that others have created. That’s where you come in.

Write up something in your blog about how you’ve used the software, especially if it describes a problem you had and how you solved it. For example, I once spent a day debugging problems getting Solr to run under the Tomcat engine. After I’d pieced together the answer from many different sources, I created a single page that dealt with the problem for future Solr users to find. As you can see from the comments on the page, it seems to be working, and I take great satisfaction in that.

Writing up the story of your problem and solution adds to the body of knowledge of the project, even if it’s not part of the project’s official documentation.

7. Give a talk at a user group meeting

There’s no higher bandwidth medium for the transfer of knowledge than face-to-face at a user group meeting. Giving a short presentation on your favorite piece of open software can get many people interested in the project and contribute their skills. You don’t have to be a great speaker, or even have spoken before, to provide great value to other attendees. In fact, some user groups hold “lightning talks” where a series of speakers give 5- or 10-minute presentations. These are a great way to get your feet wet without having to prepare (or sweat) too much.

8. Find the right project to contribute to

Finally, a quick note on a common question: “I want to get started in open source, but what project should I work on?”

The best project to contribute to is one that you actively use. Don’t worry about which project needs you the most. All open source projects need help. A project you already use is going to give you the most motivation and you won’t have a learning curve trying to figure it out. If you choose a project that you use at work, like a web framework, for example, you may get time to work on it at work, and you’ll make your work life easier as well.

Whether you’re working to improve the code of the project itself, or just help spread knowledge and attract users, it’s surprisingly easy to get started contributing to open source projects. Just take a few small steps to dip your toe in the water, and pretty soon helping the open source community will become an everyday part of your life as a software developer. And open source software will be the better for your contributions.

Don’t miss:
The 8 Essential Traits of a Great Open Source Contributor
7 Things That Make a Great Open Source Contribution


Open source image courtesy of

Andy Lester has been involved with open source for two decades, contributing many modules to Perl's CPAN as well as speaking at open source conferences and user groups around the country. He's the author of the search tool ack and his book Land The Tech Job You Love is published by Pragmatic Bookshelf. View posts by .

Interested in writing for New Relic Blog? Send us a pitch!