The Beginner’s Guide to Contributing to Open Source Projects



  • This post was originally published on May 5th, 2014. It was updated on October 10, 2018.

    The practice of building and maintaining open source software works because people from all over the world, of all abilities and backgrounds, form communities to support the projects they care about. It’s not difficult to support the open source projects you use every day, and the efforts you make will have tangible effects on the quality of that software.

    Most open source projects don’t have a dedicated staff to support them. Instead, developers and users from around the world work on them, often in their spare time. 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. Any time someone fixes a compiler warning, closes a bug, or adds to the documentation, progress is made. Put a lot of those contributions together and great things can happen.

    Ready to get started? First, consider what you can do to contribute to the projects you already use every day. If you do any sort of programming these days, chances are you’re using open source projects. Languages like Ruby and Python and frameworks like React and Node.js are all open source projects. The developer tools you use are probably open source as well. The Atom editor is open source, as is the Eclipse IDE. The Nginx and Apache web servers are open source, as are the Tomcat and Jetty serverlet Java containers.

    Start by contributing to the projects you use every day; the projects you’re most familiar with will be the easiest to get involved in. Here are five ways you can get started on your own, followed by four tips for getting involved in open source projects with other developers:

    Get started with open source on your own

    1. Report a bug to the project’s issue tracker

    Reporting an issue to the project issue tracker is one of the easiest ways to support the open source projects you use. Sometimes when we discover a bug in the software we use, we’re in no mood to go out of our way to report it. We just want to work around the problem and move on. That’s fine, but be sure to report the bug as soon as possible while it’s still fresh in your mind. Report all the details you can about how to show the bug’s behavior, and explain it just like you’d want a user to explain a bug to you.

    Sometimes, of course, the bug isn’t even in the code, but in the documentation. Maybe you’ve come across an out-of-date reference to a feature that no longer exists, or even just a typo. These documentation bugs are just as real as bugs in code, and they should be reported in the issue tracking system, as well.

    Before you submit the issue, though, make sure to search the existing bugs for the one you’re going to report. If you’ve discovered a problem with the `calcScreenResolution()` function in the library you’re using, for example, do a keyword search on `calcScreenResolution` to see if it’s already been reported. Make sure to check all the issues, regardless of status. Maybe someone’s already reported this behavior, but the ticket’s been closed.

    If you do find an open ticket for the problem, see if there’s any new information you can add. You might add a comment like, “I found that calcScreenResolution() only shows this behavior in Chrome, but not Firefox.” Details like that can be a huge help to developers working to solve the problem.

    2. Submit suggestions for features

    Good ideas on open source projects come from everywhere, including the user base. If you have a suggestion for the code or documentation, go ahead and submit it to the tracker. Just as with reporting problems, first search the existing issues to see if a similar issue has been submitted and if so, build on that.

    Documentation suggestions are especially useful. As a user of the documentation, you have a perspective that the project maintainers, who are intimately familiar with the project, do not. You can explain what parts of the documentation can use help, or explain what was confusing.

    If the issue tracker supports it, add a vote, or star, or a thumbs-up to the issue to show your support for it. This can help project maintainers know which new features users need the most.

    3. Answer a question publicly

    Time spent helping others is an investment in an open source project as much as writing code. When qualified users of the software join in to help others, the project grows as a whole. If you’re at all experienced with a given piece of 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, StackOverflow’s sister site Server Fault is a great place to help contribute your knowledge.

    Of course, many projects have their own dedicated forums, mailing lists, IRC, and Slack channels. Sign up for one and see how you can help. The newbie you help today may contribute something that you end up using in the future.

    4. Blog and tweet about what you do

    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 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 Apache Solr to run under the Apache 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.

    5. Attend a meetup

    There’s no higher bandwidth medium for the transfer of knowledge than face-to-face at a meetup or user-group meeting. If you’re close to a city of any size, chances are there are several meetups nearby.  Meetups are typically free to attend and cover all sorts of technical topics. The bigger your city, the more likely you are to find more specific topics, while smaller cities will have more general meetups. Meetup.com is the standard place to finds meetups these days.

    Although most developers go to meetups to listen to presentations and meet other people with similar interests, giving a short presentation on your favorite piece of open software can get new people interested in the project and convince them to contribute their skills. You don’t have to be a great speaker, or even have spoken before to provide real 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.

    Get started with open source with other developers

    So far, we’ve talked about ways you can contribute to open source without any sort of coordination with other people on the project. But you can accomplish even more by working directly with others.

    Many projects have overview documents for new contributors. Before you start working on your contributions, be sure to read the project’s guidelines. Look in the source tree of the project for a document called “README” or” CONTRIBUTING”—they’re aimed directly at you.

    Here are four ways you can get started:

    1. Verify and document bugs

    Assessing user-reported bugs is a huge help to the project team. Pick a bug from the issue tracker and see if you can reproduce it on your system. 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 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.

    2. Find a bug or add a feature

    Submitting code to a project is one of the most satisfying contributions, and many projects have things set up just for new contributors. Look in the issue tracker for tags like “First Timer,” “Help Wanted,” or “Newbie.” These are bugs that the project team needs to get fixed but have left for newcomers.

    Before you start working on the code, read over the project’s code guidelines. It will probably be called “CONTRIBUTING” or something similar. Follow the code guidelines and any coding standards listed there, even if they’re not exactly how you’d do it. Now is not the time to decide that you’re going to use tabs even though the rest of the project uses spaces.

    Once you’ve made a change to files in the project, you have to get your work back to the project. You don’t submit the files that you changed directly. Instead, you submit only the parts that you’ve changed, in a special format called a “diff,” for differences. This can also be called a “patch.”

    It’s likely that your project will be hosted on GitHub, which has a process called a “pull request,” where you request that the team incorporate your changes into the project. Pull requests make it easy for projects and contributors to share work.

    When you’ve fixed the bug, you’ll want to submit a patch or a pull request.

    The process of making a pull request is beyond the scope of this post, but you can refer to this pull-request tutorial for hints on making your first pull request. You may also want to check out chapter five of VM (Vicky) Brasseur’s upcoming book, Forge Your Future With Open Source.

    3. Write an example for the documentation

    Precious 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 your own working code, extract the most interesting parts, and you have a real-world example to help new users get up to speed quickly.

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

    Typically, changes to the documentation are treated just like code revisions, so you’ll probably be making a pull request when you’re done. Follow the instructions in the project’s contributor guidelines as discussed above.

    4. Ask the project what you can do for them

    Many open source projects don’t have things laid out in a handy document. So you may want to announce publicly that you’d like to help, and ask for pointers. Projects always need help on all sorts of tasks you might not think of, from updating the HTML on the project website to writing articles to updating the site design, to simple mechanical tasks like updating all the copyright dates in the source files.

    Let others on the project know that you’re available, and give them an idea of your skills. Join the project’s developer mailing list, visit the associated Slack or IRC channel, or even take to your own Twitter account, and post a message like this:

    “Hi, I’m Marcy Morgan, and I’ve been using the XYZ framework for the past few months, and it’s made my webdev work a lot easier. I’d like to help contribute to the project, but I’m not sure how I can best help. I’ve got a couple of years experience in PHP and Ruby, but I also come from a past career as a writer and artist in the advertising industry. Any suggestions?”

    If you’re posting on Twitter, be sure to hashtag or reference the account for the project so that the right people will notice it.

    No matter what your background or experience level, chances are there’s something you can do to help your favorite open source project. Start with a few small steps to dip your toes 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.

    Open source images courtesy of Shutterstock.com.





© Lightnetics 2018