The Ultimate Guide to Open-Source Contribution

Open source is everywhere.

It’s in proprietary apps and your favorite online encyclopedia. It’s happening at huge corporations and also at The Onion. From novel drug discovery to wedding invitations, you can’t avoid open source, so might as well help develop it.

Even better, involvement with open-source software can supercharge your career.

“We want you here. All the leaders within the community want that,” Drupal Association CTO Tim Lehnen said. “There are a lot of people, especially in Drupal, who built their whole careers out of showing up on IRC 14 years ago and saying, ‘Hey, is there something I can help out with?’”

We talked to open-source experts at the Cloud Native Computing Foundation (CNCF), the Drupal Association, Red Hat, Superhuman and Capital One and collected their tips for open-source contribution and how to build your presence in open-source communities.

More on Software DevelopmentHow to Deal With a Tech Lead Who Doesn’t Give You Enough Feedback

Finding a Project

Some contributors want to improve the open-source software they use at work. Others want a hand in creating new, innovative tools. And some people are just there for the experience, which Red Hat’s Kubernetes community manager Josh Berkus doesn’t mind at all.

“I have no problem with people joining Kubernetes as a resume builder,” he said. “Where it’s a problem is if they want to build their resume without doing the actual work.”

“Where it’s a problem is if they want to build their resume without doing the actual work.”

Like Berkus hints, there’s a difference between racking up commits and building real open-source experience. Even if you’re only there for the resume bullet point, it’s important that your contributions add value instead of clutter — and any savvy hiring manager will know the difference. So if you’re about to submit 100 one-line typo fixes and call it a day, step away from the keyboard.

Most contributors land on an open-source project because they’ve used the technology in their work. Maybe they noticed a bug or a missing functionality, or they want to keep an eye on the project’s trajectory. When in doubt about where and how to contribute, just follow your interests.

“Find the thing you wanted to do anyway,” Berkus recommended. “Because you’re going to end up spending a lot of time that nobody pays you for.”

Getting Started

Breaking into new communities as a first-time contributor can be hard, and project leaders know that.

“It’s one of the main things that we struggle with in the Drupal community,” Lehnen said. “People just don’t know how to take the first step.”

The good news: Big open-source projects are trying to make this easier. CNCF and other projects participate in CommunityBridge mentorship programs, which pair mentors with mentees to boost participation and diversity in open source. Drupal trains mentors to meet with new contributors at conferences and teach them how to find issues and complete related tasks.

For longer engagements, Google’s Summer of Code and Season of Docs programs connect aspiring contributors with open-source organizations for season-long paid programming or documentation projects. Outreachy does the same, with a focus on giving people from underrepresented groups opportunities to work on free and open-source software.

“The biggest challenge for most people is that they don’t identify their areas of interest and where they can help us.”

The most important step in starting your open-source career, though, is identifying what you can contribute and what you want to learn, CNCF developer advocate Ihor Dvoretskyi said.

“The biggest challenge for most people is that they don’t identify their areas of interest and where they can help us. They come to the project and ask, ‘How can I help?’” he said. “Instead, they could say, ‘This is the skill set I’d like to achieve.’ For example, ‘I’d like to develop some specific functionality for this piece of the project.’”

Want to get good at decoupled APIs or build your UX chops? Say so. It’ll help you get started more efficiently.

Making Contributions

Choosing a First Issue

Your first open-source contribution won’t be groundbreaking — and that’s OK. Leaving a comment or helping with user testing is a fine place to start. The more you participate, the more comfortable you’ll get.

Berkus said he frequently asks first-time contributors to try to set up the system from scratch and keep track of any missing pieces in the installation, set-up and configuration documentation.

“That is an immensely valuable thing to do,” he said. “And it’s something that only somebody who’s new to the project can do, because somebody who’s been working on the project for five years already instinctively knows those missing things, so they won’t even notice they’re missing.”

Kubernetes — like many open-source projects — uses the GitHub “good first issue” tag to mark issues that are good starting points for beginners. There’s also a “first timers only” tag. Use those, as well as a project’s “contributing” file, to get familiar with the preferred structure for code and pull requests.

And before you dive in, do you research. Search for the issue in the project’s release notes, newsletter, chat channel and past comments to get a sense of its history and status. If an issue has been open for a long time, ping someone or leave a comment to make sure it wasn’t resolved and then forgotten.

“A good reason to start with non-controversial contributions is that you get to know the people and some of the history.”

One more tip from Berkus: Some bugs have been left untouched because of tricky technical tradeoffs, and some issues have been the subject of months of fierce debate. As a newcomer, it’s better to stick with established, non-controversial issues, rather than accidentally stoking an argument you don’t understand.

“A good reason to start with non-controversial contributions is that you get to know the people and some of the history,” Berkus said. “So if something’s going to require a lot of rewriting or be risky in some way, you’ll know that before you propose your change.”

What if a change that looked obvious turns out to be controversial? In that case, Berkus said, let everyone know you were unaware of the background. Then, the people familiar with the debate can decide whether to drop it or make a change.

Getting Your Code Committed

First, check the release notes and see how similar problems or suggestions have been treated in the past, said Conrad Irwin, co-founder and CTO of email service Superhuman. Irwin was a frequent contributor to Wikipedia’s codebase and a maintainer on the Ruby debugger Pry.

“[If I’ve found a bug], I tend to look through the release notes. If there are a lot of bug fix releases, I feel quite comfortable that this is a relatively new project and I can jump in and help out,” he said. “If the project seems very stable, then I’ll probably just say [the functionality] isn’t acting the way I expect it to and have a discussion about it.”

Second, read the related code to make sure your bug or issue isn’t just a misunderstanding on your part. Is there something that actually needs changed or improved?

If you decide to create a pull request, make sure it’s not coming out of nowhere: Open the issue or leave a comment first. That shows you’ve given it some thought. Then, break your contribution down into digestible chunks. Getting someone to review a gigantic feature or fix is going to be tough, and segmenting your work will make for much quicker commits. But expediency isn’t the only upside to smaller pull requests.

“Looking at the code, monolithic changes are hard to QA,” Lehnen said. “Also, they’re not as reusable as they should be. So if you break whatever feature you’re creating into reusable components, that can serve multiple other initiatives and help create new APIs that serve more than just the one feature you have in mind.”

For more complex features, Lehnen suggested a quid pro quo: Offer to review someone else’s work in exchange for their review.

If you have a loftier idea that needs community buy-in, skip the five-paragraph persuasive essay, Berkus said. Nobody likes the person who shows up in a new environment and tries to change everything — we all learned that from Friday Night Lights.

“Community structures are a lot like any other organization, in that it comes down to understanding who the stakeholders are and who it’s worth your time to build alliances with.”

Instead, focus on the people who could help your idea gain traction, Capital One’s John Mark Walker said. Walker is the director of the company’s open-source program office, which oversees the release of open-source projects like Hygieia and Cloud Custodian.

“Community structures are a lot like any other organization, in that it comes down to  understanding who the stakeholders are and who it’s worth your time to build alliances with,” Walker said. “Part of that means taking feedback from every conversation and evolving the idea over time so that, by the time you get to a point where you’re ready for a wider discussion, there’s already some acceptance among key stakeholders.”

To find out who’s working on what, start by checking internal org-structure documentation, issue trackers and newcomers forums. Attend any all-hands meetings and see who talks about what. If you’re still confused, reach out to a project maintainer or notable contributor — but preface your message with, “Is it OK if I ask about this?”

Those people get pinged constantly, Berkus said, and many are tired of fielding questions.

As you talk about your idea with other community members, you may even find that other people have pitched the same thing. When that happens, joining with existing efforts is better than striking out alone, Lehnen said.

When Maintainers Say ‘No’

Often, maintainers and other contributors will work with you to fine-tune contributions. But even if you’ve done your research and honed your ideas, some issues and pull requests will still get shot down.

In some cases, explaining your reasoning can lead to more clarity for everyone. Irwin experienced this firsthand when submitting a change to the Wikipedia codebase:

“The lead developer of Wikipedia came back to me and was like, ‘What on Earth are you doing?’ And I was like, ‘Um... I don’t know.’”

“The lead developer of Wikipedia came back to me and was like, ‘What on Earth are you doing?’ And I was like, ‘Um ... I don’t know,’” he said.

Irwin was thrown off — he knew it was the right fix, but he hadn’t presented it the right way. It took him a long time to unwind his pull request and articulate exactly what it was he was trying to solve, he said. Then he went back to the maintainer.

“As soon as he understood, he said: ‘Oh, I see what you’re trying to fix. Did you know you could do it this way?’ My pull request had made no sense. Not because it didn’t fix the problem I was seeing, but because, architecturally, that’s not how they did things,” he said.

If you can’t adjust or re-package your rejected pull request to add value to the project, it’s better to take that “no” at face value and move along. Irwin is fairly conflict averse, he said, so rather than argue, he tried to take his ideas elsewhere.

For example, after a previous Gist Gem maintainer rejected a bunch of bug fixes Irwin had submitted, Irwin created his own, separate Gist Gem. He worked on it for months before someone who knew both him and the original project maintainer helped create a truce. The original maintainer was burnt out, and Irwin’s enthusiasm — and shiny new code — ended up giving the project a fresh start.

“I just took over his project and kind of overwrote it with the code that I’d been working on,” Irwin said. “That was a really good example of good communication. Because we had a mutual friend who was able to introduce us over the internet, we were able to hash it out.”

What If I Don’t Code?

Glad you asked. Lehnen had some choice words about the value of contributors from non-technical backgrounds: “I am now the CTO for a big open-source project, and I’m an English major.”

Lehnen has a background as a coder, but many open-source contributors don’t touch the codebase at all. In fact, one study found about a quarter of casual contributors stick to documentation changes and fixes.

“Documentation in open source is weak, and it tends to be written by the people who just wrote the code,” Irwin said. “There are so few open-source projects with good explainer docs.”

“I am now the CTO for a big open-source project, and I’m an English major.”

If you’re interested in technical writing, Write the Docs has a collection of resources on contributing to open source. Fixing mistakes and filling in gaps in documentation is also a good way to ingratiate yourself to a new open-source community, Walker added.

But the potential for non-code contributions doesn’t end there. Dvoretskyi helped bootstrap a product management special interest group in the Kubernetes community. Now, he co-leads the group and has served as a features lead for multiple releases.

Other people create marketing assets, organize meet-ups and conferences, write blogs and newsletters or help improve a project’s UX. This work is an essential part of the open source ecosystem, and projects want contributors with these skills.

“People who have communication, collaboration or project management skills are actually really well primed to become not just contributors in an open-source community, but leaders,” Lehnen said.

Leveling Up

Building Your Skills

Professional growth in open-source spaces is, in some ways, easier than in traditional work environments. Nobody’s going to interview you or ask to see your resume, Dvoretskyi said, and if you want to learn a particular skill, you can seek that out.

For example, if you want to build product management skills, figure out which people are performing that role in the community, and spend some time studying how they approach their work. Eventually, you could raise your hand and ask for opportunities to help with project management, product roadmapping or features planning.

Kubernetes has a shadowing program that lets contributors apply to spend a release cycle supporting people in leadership roles. When that cycle is over, mentees have the knowledge to take on more responsibility during the next release, while mentors can take a break. Applications are sent out via mailing list about once every three months, Dvoretskyi said.

Taking on More Responsibility 

Open source has a problem with maintainer burnout.

“It’s not just open source,” Lehnen said. “Any organization that uses volunteers is prone to fall into this trap: ‘Hey, Tim. You’re good at this thing, so please do it forever until you burn out and die.’”

Yikes.

The good news is that projects are aware of this, and many actively build programs to funnel newer contributors into leadership roles. Drupal has a matching mechanism for volunteer opportunities that build visibility in the community, said Heather Rocker, executive director of the Drupal Association. It also has a set succession pipeline for leadership roles.

“That gives us a better view of who’s helping where and whether we’re supporting them and giving them the tools to succeed,” Rocker said. “But also, how do we make sure the same person hasn’t led the same thing for 10 years?”

Similar to CNCF’s shadow program, the succession program pairs existing leaders with aspiring ones, so new people can learn the ropes and long-time maintainers can transition out.

When Irwin was an active open-source maintainer (he’s still the official maintainer on a couple of Ruby gems, he said), whenever someone sent a really high-quality pull request, he’d add them as a collaborator who can merge pull requests on their own. That way, if he no longer had the time or interest to work on the project, there would be plenty of qualified people to keep it going.

“In some cases, no one takes over, and projects wither away,” he said. “But in other cases, I’ve had people who are now de facto maintaining it on my behalf.”

Finding a Community

Building Relationships

Irwin joined the Pry community to submit a couple of bugs and features he wanted. He started chatting with the maintainers, and then hanging out in “real life,” he said. They’re still friends today.

Making friends in your open-source community is the same as making friends anywhere else. Spend enough time there, and you’ll get to know people. But there are things you can do to speed it along. Here’s what Walker suggested:

• On Slack — or whatever chat tool your project uses — take the time to answer questions and help other people solve problems.
• When you learn something new, share it with everyone.
• Help newcomers make connections and get up to speed. 

Communicating Well

Good communication can be as important as strong technical skills in open source. The same patience, collaboration and politeness that helps in the office will help in online communities.

While a lot of these so-called soft skills carry over, Dvoretskyi said one of the trickiest things about open-source communication is remembering that your collaborators live all around the world. So relying on American slang or shorthand — or scheduling every meeting in Eastern Standard Time — isn’t going to work. Instead, keep in mind that many contributors are using English as a second, third or fourth language, and remember that important meetings can happen more than once to accommodate different time zones.

Dealing With Negative Behavior

If you’re worried about feeling unwelcome in an open-source project, you’re not alone.

Many open-source projects have codes of conduct to govern contributor behavior, and thousands have adopted the Contributor Covenant, a drop-in code of conduct that focuses on supporting diversity and inclusion.

The Contributor Covenant was created by developer and advocate Coraline Ada Ehmke in 2014 in response to “unwelcoming” or “hostile” behavior in open-source communities. Unfortunately, that type of behavior has been a festering problem for some projects. According to a 2017 survey by GitHub, 50 percent of open-source participants had witnessed negative behavior, and 21 percent of that group chose to leave a project because of it.

“The fallacy is that somehow by rejecting those people who behave badly, you’re losing out on that talent.”

Women are more likely to come across behavior in open source that makes them feel unwelcome, the survey found. That may be one factor in women’s abysmally low open-source participation — GitHub estimated that 95 percent of participants are men. (For reference, women make up about 20 percent of software developers in the United States.) Women are also less likely to get pull requests accepted — unless their gender isn’t identifiable. Then, they’re more likely to see their code committed.

Lots of open-source projects are taking steps to make their communities more diverse. Drupal created a working group that examines any gaps in enforcement of the community’s code of conduct and creates reporting mechanisms for people who experience discrimination or harassment. It’s also trying to make its conferences more inclusive by making a rule against “manels” (all-male panels, Rocker clarified). Walker called out Python as a community that’s setting an example by building connections with minority participants and creating a welcoming vibe. And Mozilla created a Firefox extension to obscure the identities of patch authors on Bugzilla and GitHub pages.

In the end, inclusivity is a matter of community commitment, Lehnen said. Is the community willing to stick up for newcomers and remove people who behave badly?

“In some cases, open source has felt like a haven for people who don’t have the social skills to work at other places. They feel like here, it’s just about their technical knowledge, and therefore this space belongs to them,” he said. “The fallacy is that somehow by rejecting those people who behave badly, you’re losing out on that talent. But I think nobody’s bothered to measure how much talent you’re losing by not having a welcoming space for other types of people.”

More on Software DevelopmentHundreds of Volunteers Are Fighting Pandemic-Inspired Cybercrime