Contributing to open source projects is one of the best ways to learn, even if you’re a new programmer. The purpose of this document is to provide a basic outline of how you can begin contributing to open source projects and what to expect once you are doing it.
If you’re interested in contributing to open source projects but don’t know where to start, this handy guide offers suggestions for places to look for both bugs and feature requests that are good candidates for contributions from new developers. Even better, it provides advice on the best ways to get involved with a project. By the end of this guide, you’ll be more familiar with how open source projects work, ready to post your first pull request, and prepared for a lifetime of participating in an open source community!
Understanding how a project works
Not all open source projects operate in the same way. Some allow contributions from anyone. Some require you to work your way up to get contribution privileges. Some have multiple people involved in managing a project. Others have a single person in charge, a so-called benevolent dictator for life.
Contribution guidelines help you understand how to approach your participation in a project. It will explain how to reach out about a contribution, provide templates for communicating bugs and suggesting features, list work that is needed by maintainers, project goals, etc. An amazing example is the Angular contribution guide which lists all kinds of useful information for new contributors like their commit message guidelines, coding rules, submission guidelines, etc. in great detail.
In addition to contribution guidelines, some projects will have a code of conduct. It usually outlines community rules and behavior expectations. It’s meant to help you know how to be a amiable and professional contributor and community member. Angular, for instance, has an awesome code of conduct that lists what they consider unprofessional conduct, their responsibilities to the community, and how to get in contact in case someone violates it.
Big projects may have governance policy and team documents that outline specific roles in the community, teams, sub-committees, contribution workflows, how discussions are conducted, and who gets to commit. These kinds of documents are essential to understanding how the community operates. The about page on angular.io, for example, lists who all the core team members are, their roles, and other contributors. On Github, they also have a docs folder containing policies regarding contribution.
Even after you’ve gone through the documentation, you may still need to ask questions to active members of the community. Despite doing your research, you may still be stumped on a particular aspect of the project. To interact with other contributors, join community communication tools like Slack, IRC etc., sign up for newsletters, and subscribe to their mailing list. Angular uses Gitter as its community communication tool and directs contributors with questions/problems to Stack Overflow, where they can get help using the
angular tag. Connect with community members and develop relationships with them as it will expose you to facets of the project that you may be unaware of.
Having a good grasp of the technical aspects of the project and how it’s organized is essential to making contributions that meet the project’s standards. To understand technical parts of the project, consult the project README, wikis, tutorials, and documentation. Angular, for example, has docs explaining their Github process, building and testing, their coding standards, debugging, PR reviews, etc. Going a step further, look at past feature integrations and bug fixes in merged pull requests which are full of discussions by other contributors and can be a rich source of context. As the project evolves, pay attention to it, frequently follow issues, features, discussions, pull requests, and bug fixes to continually learn how it works. For instance, a contributor can follow this example of an Angular feature request discussion about a form API to better understand how Angular forms work, bundle size management, etc.
An open source project is sort of like a project at any company you might work at; there will be a house coding style, team culture, and workflows for getting things done. The difference is that open source projects can and will have a much different group of people working on them.
Work with Tickets
Code is the heart of any open source project, but don’t think that writing code is the only way to contribute. Maintenance of code and the systems surrounding the code often are neglected in the rush to create new features and to fix bugs. Look to these areas as an easy way to get your foot into a project.
Most projects have a publicly visible trouble ticket system, linked from the front page of the project’s website and included in the documentation. It’s the primary conduit of communication between the users and the developers. Keeping it current is a great way to help the project. You may need to get special permissions in the ticketing system, which most project leaders will be glad to give you when you say you want to help clean up the tickets.
4. Diagnose a bug: Bugs are often poorly reported. Diagnosing and triaging a bug can help save the developers save time with the legwork of figuring out the specifics of the problem. If a user reported, “The software doesn’t work when I do X,” spend some time to figure out the specifics of what goes into that problem. Is it repeatable? Can you create a set of steps to cause the problem repeatedly? Can you narrow down the problem, such as only happening on one browser but not another, or one distro but not another?
Even if you don’t know what causes the problem, the effort you put into narrowing down the circumstances makes it easier for someone else to fix it. Whatever you discover, add it to the ticket in the bug system for all to see.
5. Close fixed bugs: Often bugs are fixed in the codebase but tickets reported about them don’t get updated in the ticketing system. Cleaning up this cruft can be time-consuming, but it’s valuable to the whole project.
Start by querying the ticket system for tickets older than a year and see if the bug still exists. Check the project’s release change log to see if the bug was fixed and can be closed. If it’s known to be fixed, note the version number in the ticket and close it.
Try to recreate the bug with the latest version of the software. If it can’t be recreated with the latest version, note that in the ticket and close it. If it still exists, note that in the ticket as well and leave it open.
Finding projects to work on
One way to find projects to work on is to look to open source software you use often and like. Is there a tool, package, framework, or a language that you work with regularly and enjoy using? Find out whether it’s an open source project by checking its license and if it accepts contributions and is active. Working on things you already use gives you an edge when contributing because you’re already pretty familiar with how it works and have experience using it. As a bonus, you can address problems that have been bothering you or suggest features that you want in the software. If you are going to contribute code to the project, be sure you can work in the language it’s written in.
If the above approach may not work for you, try using the Github explore page to find projects that are accepting contributions or actively want help. Github suggests projects you may like based on people and repositories you follow, star, and watch. Another way to find projects is to use Github’s search tool by entering beginner-friendly contribution tags like good-first-issue, good-first-bug, beginner-friendly, easy, low-hanging-fruit, first-timers-only, etc. Filter search results to return issues in open states and in the languages you’d like to work in. There are tons of other tools, platforms, and programs where you could find open source projects that I’ll list at the end of this article to help you with your search.
To have a positive contribution experience, try to avoid communities that are hostile to beginners and generally problematic. If for example, when trying to ask legitimate questions after you’ve done your research, you receive dismissive and combative comments or insults, it’s best to stay away. Another sign to be watchful for is a pattern of unprofessional behavior within a community. Some open source software projects have been infamous for this sort of thing. So do your research before contributing.
Working with Code
Programmers of all experience levels can help with the code in the project. Don’t think that you have to be a coding genius to make real contributions to your favorite project.
If your work involves modification to the code, investigate the method that the project uses for getting code from contributors. Each project has its own workflow, so ask about how to do it before you set out to submit code.
For example, the PostgreSQL project is very rigorous in its process: Code modifications are sent in patch form to a mailing list where core developers scrutinize every aspect of the change. On the other end is a project like Parrot where it’s easy to get commit privileges to the codebase. If the project uses GitHub, there may be a workflow that uses the pull request feature of GitHub. No two projects are the same.
Whenever you modify code, make sure that you act as a responsible member of the community and keep your code style to match the rest of the codebase. The code you add or modify should look like the rest. You might not like the bracing style or the handling of spaces for indentation, but it’s rude to submit a code change that doesn’t match the existing standards. It’s the same as saying “I don’t like your style, and I think mine is better, so you should do it my way.”
6. Test a beta or release candidate: Any project that’s designed to run on multiple platforms can have all sorts of portability problems. When a release approaches and a beta or release candidate is published, the project leader hopes that it will be tested by many different people on many different platforms. You can be one of those people and help ensure that the package works on your platform.
Typically you only need to download, build, and test the software, but the value to the project can be huge if you’re on an uncommon distribution or hardware. Just reporting back that the build and test works helps the project leaders know that the impending release is solid.
7. Fix a bug: This is usually where contributors wanting to get working on code start. It’s simple: Find an interesting-sounding bug in the ticket system and try to fix it in the code. Document the fix in the code if it’s appropriate.
It’s a good idea to add a test to the test suite to test the spot of code you fixed; some projects require bug fixes to include tests. Keep notes as you poke around this unfamiliar codebase. Even if you aren’t able to fix the bug, document in the ticket what you discovered as part of the fix attempt. What you find helps those who come after you.
8. Write a test: Most projects have a test suite that tests the code, but it’s hard to imagine a test suite that couldn’t have more tests added to it. Use a test coverage tool like gcov for C, or Devel::Cover for Perl to identify areas in the source code that aren’t tested by the test suite. Then, add a test to the suite to cover it.
9. Silence a compiler warning: The build process for many C-based projects often spew the odd compiler warning flag to the screen. These warnings are usually not indicators of a problem, but they can look like it. Having too many warnings can make the compiler sound like it’s crying wolf.
Check to see if the code could actually be hiding a bug. If not, modifying the source to silence helps to hide these false positives.
There are many ways to contribute to open source projects and we should never feel shy about what we can do. Maybe you don’t have a specific thing in mind but rather, would like to simply contribute.