How to Successfully Contribute to Large Open Source Projects

Open source can be a lot like prison. (Stick with me.) In prison there’s an old adage that, on your first day, you should find the biggest inmate and punch them in the face. The idea is that you’ll immediately establish your credibility as the biggest guy/gal in the place, and no one will want to mess with you.

In the open source world, a lot of developers jump into a new project like they’re entering prison; these developers aren’t literally punching people, but they do conform to the same adage—that is, they feel the best way to start contributing is to fix the hardest bug in the issue tracker to establish their knowledge of the tool. This approach almost always ends badly, both in prison, and in the open source world. (Technically I’m just assuming it ends badly in prison, but I can’t imagine punching the largest inmate in the face works out well for many people.)

Generally speaking, open issues are open for a reason. If a bug is trivial to fix, or a feature is easy to implement, the maintainers of the project would have just made the change and closed the issue. Open issues usually have some repercussions, or some non-obvious implication that isn’t immediately obvious to a developer stumbling upon the problem without any context.

And as a broader point, most successful open source contributors don’t start with code. Successful contributors start by getting involved in the project in other ways, like support and documentation, and then move on to coding when they’re more comfortable with the project and the team that maintains it.

I’ve seen this firsthand, both as someone who went from a jQuery community member to a jQuery team member, as well as my current involvement on the NativeScript project. As such, I thought I’d share an opinionated set of steps for how to become a contributing member of a large open source project. I’ll preface the article by saying that not all projects are the same, so obviously not all of this advice will apply to your favorite project, but I’ll back up my arguments with concrete examples from the NativeScript and jQuery projects to prove my points.

Step #1: Support

Support is the single easiest way to contribute to an open source project. Large open source tools generate an enormous number of community questions, requests, and discussions. Project maintainers can only feasibly participate in so many of these conversations, and as such, community support is invaluable to keeping the project running smoothly.

The specifics of how to get involved in support can vary from project to project, but here are some common ways you can help.

Stack Overflow

Most large open source projects have a non-trivial amount of questions on Stack Overflow, and those questions are only useful if someone answers them. Answering Stack Overflow questions is a great way to learn more about a project, as you’ll be forced to research and learn parts of the tool that you haven’t used before.

Stack Overflow is how I personally got started contributing to jQuery. Most of my precious ~8,000 Stack Overflow reputation points were earned on jQuery UI questions, and spending time on those questions helped me learn jQuery UI at a deeper level. I started to dive into the source code to investigate problems, and familiarize myself with how the project was built.

If you want to get involved on Stack Overflow yourself, start by finding the tag for your project of choice on stackoverflow.com/tags. Bookmark your favorite project’s tag — here’s NativeScript’s, for instance — and return to that page periodically. When you see questions come in see if you can answer them, and if you can’t, do a bit of research to try to get to the bottom of the problem — especially if it’s an area of the project you’d like to learn more about anyway.

If you’re really motivated to help, I’d recommend heading to stackexchange.com/filters, and configuring a filter that emails you new questions for your tag(s) daily. For example, here’s the filter I have set up for NativeScript.


Configuring a Stack Overflow email filter for the “NativeScript” tag

The daily emails give me a list I can quickly skim for questions I might be interested in answering.


An example of the daily Stack Overflow email with new questions

I personally enjoy answering questions on Stack Overflow because it’s a resource that’s helped me countless times over the years. It’s been fulfilling to feel involved in the tool, if only a little. But Stack Overflow isn’t the only way to help support an open source project—another common place is chat.

Chat

Most large open source projects have a public or community chat of some fashion. jQuery has IRC; Angular has Gitter; and for NativeScript we use Slack. Regardless of the software, chats tend to bring in people that have questions or need help using the project in question. Much like Stack Overflow, getting involved with the chat around a project is a great way to learn more about it, as well as learn the common pain points that people are running into.

Unlike Stack Overflow, chat is a great way to form personal relationships with the people behind a project. Project maintainers tend to hang out in the chat about their project, and they definitely recognize and appreciate when others step in to help. I met the jQuery team through IRC, and I’ve met most of our Telerik Developer Experts through Slack.

This relationship helps build trust between you and the project maintainers. This trust goes a long ways if you intend to start committing code at some point in the future. For NativeScript, if I see a pull request from one of our experts, I’ll trust that PR a lot more than a random person I haven’t met before.

Overall, providing support – whether it’s on Stack Overflow, a forum, Slack, or wherever — is a great way to learn more about a project, and to prepare yourself for contributing code directly. And when you are ready to open up your favorite git client and go to work, the easiest place to start is not with code — it’s on documentation.

Step #2: Documentation

Documentation is perhaps the thing your average developer complains the most about — and that’s saying something! Maintaining a large open source project is incredibly time consuming, and it’s common for bug fixes and crucial features to be prioritized over the documentation to actually use the tool. Because documentation is often under-maintained, project owners tend to be far more receptive to documentation contributions than code contributions; in practical terms, this means your documentation pull requests are far more likely to be merged than your code pull requests.

And from a contributor’s standpoint, there’s a lot of value in writing documentation. First, much like providing support, writing documentation is a great way to become more familiar with a project or tool. The best way to learn a concept is trying to teach it to others, and large open source projects have massive audiences looking to learn from the project’s documentation. Those same large audiences can give you a real sense of satisfaction for the work you put in; you really are genuinely helping a ton of people.

And as an outsider you bring a unique perspective to the documentation process. Oftentimes project maintainers are so entrenched the tool they work on, they lack the ability to see the tool from a beginner’s perspective. Things that are obvious to long-time project maintainers can be immensely complex to a newcomer.

If all of this sounds appealing, and you want to get started contributing to a project’s documentation, start by finding where the project’s documentation lives. The jQuery project has several documentation repositories such as jquery/learn.jquery.com, and jquery/api.jquery.com; the Angular project’s documentation is in the angular/angular.io repo; and for NativeScript our docs are at NativeScript/docs on GitHub.

The next step is to identify things that need to be documented. Look through the open issues for labels such as “up-for-grabs” or “help wanted”. For instance here are some of the “up-for-grabs” issues on the NativeScript documentation.


Some of the “up-for-grabs” NativeScript documentation issues. You can help fix these!

If there’s a common pain point in the project that you’re aware of, and you don’t see an open issue for, open a new issue that documents the problem and offer to write the documentation yourself. If you’re not hearing back, you can write the content as a blog post and offer to contribute the content to the documentation.

Alternatively, just reach out to the project maintainers directly and ask how you can help. Usually project maintainers have some idea of where the documentation can be improved, and are happy to help point you in the right direction, especially when you’re offering to help them out.

Once you’ve gotten involved in support, and have toyed around with the project’s documentation a bit, you’re ready to move on to another common area open source projects need a lot of help: issue management.

Step #3: Issue management

Large open source projects generate an enormous number of GitHub issues, and managing those issues can be an enormous time sink for development teams. For example, at the time of this writing the Angular project has ~1,100 open issues — yes, that’s one thousand one hundred! And it’s not that the Angular team is being negligent with issues, as having a huge issue list is not uncommon in large open source projects.


The Angular project gets a new issue in every few hours

But having this large open issue list creates all sorts of problems for development teams. The biggest problem is time, as the time it takes to sift through the massive quantity of incoming issues is time that could be spent developing new features, or writing documentation. Large issue lists also make search difficult, and make it hard to differentiate between critical issues and trivial ones. At some point incoming issues can become a blur, and it’s easy to start ignoring incoming issues entirely.

As a community member there are a number of ways you can help with your favorite project’s issue management. The easiest way to get involved is to go through old issues, and try to recreate the reported problem with the newest version of the framework. Oftentimes you’ll find issues that have either been fixed or are no longer relevant. After you investigate, leave a comment on the issue regardless of the outcome. If the problem has been fixed the issue can likely be closed, and if not, the development team now at least knows the problem still exists without having to verify that fact themselves.

While you’re at it, keep an eye out for any issues that are clearly duplicates. If you find any, leave a comment in the newer issue to inform the project maintainers that the issue can likely be closed. Overall, anything you can do to save the core team time, and to help reduce the open issue count, will be greatly appreciated by the project maintainers.

On a personal level, these issue management techniques were my next step for getting involved with jQuery UI. Mike Sherov and I took a few weeks and went through every issue in the jQuery UI bug tracker, verified all issues were still relevant, verified all issues had reproducible test cases, and flagged all the duplicate issues we found in the process. That experience helped me learn a lot more about jQuery UI, and eventually led me to contributing to the source code directly.

Step #4: Code

If you spend a lot of time in your favorite project’s issue tracker, you’ll eventually find issues that are really easy to fix. My first commit to jQuery UI was removing a bit of code that was for a browser the project no longer supported (Opera 11). It was a good starting point because the code change was trivial, and gave me a chance to learn the processes the jQuery team uses — such as how to format a commit message, which git branches to use, and so forth. Learning these processes is often the hardest part of contributing code.

Kent Dodds, who has spent a lot of time writing and talking about lowering the barrier to entry for first time contributors might have said it best:

“The hard part of getting into open source for the first time isn’t the implementation of a feature, but figuring out how to actually contribute code.”

Some projects make this process easier than others. The Angular project has a really thorough guide to contributing, and the jQuery project has an entire site dedicated to contributing to the various jQuery projects. If you’re in a random project you’d like to contribute to, one thing to look for are issues with an “up-for-grabs” label. There’s even a site, up-for-grabs.net, that aggregates these labels across various open source git repositories.


up-for-grabs.net aggregates issues specifically curated for new contributors.

However, even with initiatives like “up-for-grabs”, there’s a reason I put code as the last step on this list. Jumping straight into code before becoming familiar with how a project works will be incredibly difficult for most people. Even if you manage to address the issue perfectly, and follow all contributions guidelines to a tee, there’s a decent chance your change will never be merged if you’re committing to a large project. If the core team doesn’t know who you are, you’re just another avatar adding to the wave of issues and pull requests they have to deal with everyday.

Where to go from here

Large open source projects are very difficult to manage, and project maintainers have to deal with a lot of noise that gets in the way of developing their projects. The best way you can help is by working to reduce that noise—mostly in venues like forums, Stack Overflow, Slack, and issue trackers.

Project maintainers notice people that save them time. I saw this from the contributor side when I worked on jQuery, and I now see this on the maintainer side with NativeScript. I find the work that Nathanael, Brad, Osei, Steve, Nic, Josh, Nathan, Nick, Mike, Alex, George and so many others have done invaluable, and we try to do everything we can to recognize the work these experts have done for us.

Contributing to a large open source project has all sorts of benefits. At a minimum contributing improves your skills as a software developer, and improves your resume by having your name publicly associated with a major project. I’m mostly in a position to write an article on this blog because of my jQuery contributions, and I know of many others with similar stories.

And, in my experience, the best way to successfully become a contributor is to establish trust with the core maintainers. Once you know who these people are on a personal level, you open the door up to all sorts of other opportunities. I am very grateful to have worked with many smart people when I was on the jQuery project, and I feel the same way about the NativeScript community I work with now.

If you’d like to help with NativeScript, join our community Slack channel, check out the open questions on Stack Overflow, and look through the “up-for-grabs” issues on our docs. If all else fails, ping us on Slack and just say you’d like to help; we’d love to have your help making NativeScript a better project for everyone.

Comments