Contributing to Open Source
“Open source” is one of the oldest buzzwords in software. Unlike other software buzzwords, however, open source has remained relevant for almost 30 years — almost every major modern software package uses open sourced components in some form or function. The invaluable work of open source contributors has propped up some of the most important pillars of our digital infrastructure — ranging from GNU/Linux, the operating system that runs 68% of all web servers, to WordPress, the content management system that powers approximately 31% of all websites.
Before proceeding, I think it’s important to clear up what this article is and what it isn’t. This article is not meant to laud the auspices of open source or talk about why the bazaar is superior to the cathedral. In fact, I personally believe that there are many flaws in the modern open source methodology, some redeemable, others not. That doesn’t change the fact that open source is ubiquitous. As a creator and consumer of software, you have (or inevitably will) benefit from open source work — work that is often done for free. This article captures my personal experience in getting started with open source and aims to shed light on how others might do the same.
Finding a Project
The most difficult part of contributing to open source is finding a project that is worth contributing to. This criterion is different for every individual, and this is part of the reason why open source has thrived for so long — developers have a wide enough range of interests that even the most niche open source projects will have users and staunch supporters. However, in personal experience, interest alone was never enough to spur a serious contribution. There have been plenty of projects that have piqued my interest, and yet, contributing to those projects always seemed intimidating and out of reach — a feeling I suspect many coders experience when making their initial foray into the world of open source.
The best projects to contribute to are those that you actively consume. If you are actively using a software library, you are an ideal contributor because you have intimate knowledge of what that project does and how it functions. Simply being interested in a project lacks the inherent experience component that makes contributing to open source approachable. The more you use a project, the more likely you are to find a need within that project — this could come in the form of a documentation tweak, a patch, or some other sort of contribution to the wider community.
The more code you write, the more projects you’ll come to consume, and as a result, the more open source contribution opportunities that you’ll find. At Indigo, we recently shifted towards a set of observability tools that includes Elastic Application Performance Monitoring (APM). Many of our internal APIs are written in python, which meant that the python version of the Elastic APM agent would see heavy usage in many of our repositories. My team was an early adopter of the Elastic APM within Indigo, and I got a lot of hands on experience with the python agent. While assessing our needs, it became clear that there was a key feature that we needed that didn’t currently exist in the python agent — I viewed this as an opportunity to drive value for our organization as well as the wider community of users around the Elastic APM python agent.
When you’ve identified a change you’d like to see in a project (either a bug fix, feature), it helps to first look at the list of issues in the project to see if other users of the project are talking about the changes you have in mind. If you do find an existing issue, the conversation in that thread could help you find work-arounds or learn about any existing work around resolving that issue. This is a great way to build context and develop an understanding of the state of the project and how your envisioned changes fit in.
If you don’t find an issue, create one yourself! Opening an issue creates an initial dialogue between yourself and a project’s maintainers and engaged users — this dialogue can provide invaluable context. For example, the maintainers might illuminate some technical nuance that might serve as a prohibitive blocker for your suggestions, they might point you towards active work around the idea you proposed (usually the case of duplicate issues), or they might be able to provide support in some other way. In any case, the foundation of an effective open source community is communication, and opening an issue describing the problem is always a great way to develop rapport with project maintainers and make impactful contributions.
Proposing Changes Via Pull Requests
After you open an issue and (hopefully) get some feedback, the next step is to take a crack at implementing your feature or bug fix by creating a pull request. Pull requests are how you get your changes merged into the original codebase. For most open source projects (at least those hosted on GitHub), you need to create a fork of the project you wish to contribute to and make your changes to a feature branch within your fork. After your changes are ready, you open a pull request to the original project with the intent to merge your fork’s feature branch into the main branch of the original project. This process is nicely summarized by this post on how to fork repos, and this post on how to create a pull request from a fork.
Many open source projects will have a suite of tests that your code needs to pass before your changes can be considered for a merge. Effective tests are the cornerstone of any sustainable codebase — they help ensure any changes in code don’t break any fundamental assumptions or functionality. Well written tests also serve as a form of documentation — good code is often self-documenting, and this sentiment extends to good tests. Make sure to pay special attention to test cases surrounding your code changes (a fully passing test suite is just the first step towards deploy ready code), and add any additional test cases that are necessary to cover the changes you made (your goal is to improve a project through your contribution, and untested code is akin to technical debt).
Before your changes can be merged, you need to receive approval from the project’s maintainers — a process that varies project to project. It’s important to remember that many maintainers have day jobs, families, and lives outside of open source. They often contribute to these projects in their spare time, so exercising a little patience and courteousness goes a long away.
Depending on the scope of the changes in your pull request, the maintainers will typically provide you feedback and guidance towards on additional changes you should make before they can approve your request, or they will provide an immediate approval if things look good from their perspective. Feedback typically comes in the form of comments on the pull request, which allows the pull request to serve as a living record for all the conversation that went into a particular change. After your PR gets approved, you’re good to go! A maintainer will eventually merge your changes, and the project will have benefited from your work.
Contributing to open source is much more approachable and enjoyable when contributing to projects that you actively consume. It’s important to remember that no change is too small. My first open source contribution ever was a correction to the documentation on build processes for Read the Docs.
28% of casual contributions to open source are documentation, such as a typo fix, reformatting, or writing a translation.
Your changes can be as small as fixing a typo, or as large as an entire feature — the scope is entirely dependent upon you and what you want to take on. My personal contributions were bore out of necessity — I was building something else, and along the way, I discovered a bug in some piece of software that my project depended on.
There are, of course, other ways to contribute, but I’ve found that the best way to contribute to open source is to keep on using open sourced software — you’ll inevitably find ways to contribute.