Sharing is caring: Building clearer contribution paths to your community

One of the most important topics in the open source community is "how do we attract more people to our community?" This makes perfect sense because you can’t have a community without people. Given the importance of inviting people to a community—otherwise known as onboarding—you would expect a lot of discussion and debate applied to the topic. And yet, there are many open source community managers frustrated by a lack of new contributors. 

Part of this is due to the bias that “users” comprise the entirety of a community, and if your project’s output has users, viewers, or what have you, then you have your community well in hand. For some projects, that is certainly true, and will always be true. But for other projects, this can be a lost opportunity to grow the community into a healthier project with creative input alongside creative output.

Onboarding is something we have worked to codify in Red Hat’s Open Source Program Office. For our team, we believe user-based onboarding should be based on three straightforward principles: 

• Is it clear what the project and its software does?

• How easy is it for people to get their hands on the software to start using it?

• Is it simple for interested parties to contribute to your project?

In this post, we’ll focus on that last principle around contributors, an important component of project success.

3 core principles of contributor onboarding

When discussing onboarding for contributors, there are also three core principles that should be followed:

• What can contributors add to the project?

• Where do contributors add to the project?

• How do contributors add to the project?

The first principle of contributor onboarding is one that needs a lot of work: incoming contributors need to know what would be the most helpful contributions they could make. Quite a few projects have set up tagging on their source code repositories for “first-time contributors” or something similar, which is an excellent way to direct incoming contributors to solving issues and bugs while also introducing  newcomers to the source material of the project. Unfortunately, this is not a universal process, and it is one that we are starting to work on ourselves.

The answer to the question of “where to contribute” is often present, but not as often as one would think. A lot of project veterans will dismissively say, “it’s on Git-something-or-other.” Sure, but which organization? Which specific repository? What about other similarly named projects? The rule of thumb we have for Red Hat-stewarded projects is ensuring there are clear links to contributing to any project on a project’s web property and that the links are not buried, either (they should be right on the home page, if possible).

Along with those links to the source materials should be a prominent answer to the question of “how to contribute.” Our team sees many projects that release their source code, even make it easily discoverable…and that’s it. This is something we refer to as “throwing it over the wall,” and it is not a politely used phrase. Too many projects will push their code or content out to a public space, declare it open to all, and then wonder where all the contributors are. This can be because there is a real barrier to entry, in the lack of documentation and procedures on getting contributions into the project.

Before you think we are going to start beating the “woe for the lack of documentation” drum again (and we really could), it is important to note that documentation does not have to be the sole solution to the “how to contribute” problem. Many successful projects will build pull request and issue templates that contributors can simply “fill in” once they open something up to begin the contribution process. This process acts as a built-in system that can help answer many questions about contribution.

This isn’t to say that documentation isn’t needed at all, but instead of the big “monolithic” approach to documents, a more modular approach can work wonders and not be as intensive to create and maintain. Consider creating an initial contributors’ guide that covers:

• How to contribute

• Resources for questions

• Governance

• Code of conduct

None of these sections has to be very long or comprehensive. Relate the key parts of the process in each section, and keep things simple and brief. “Governance,” for example, tends to make people’s eyes glaze over when I mention it as part of a community project’s formation until I remind them that at bare minimum, governance is not about by-laws and committees, but really just about who resolves conflicts when conflicts happen.

It boils down to “Why?”

Contributor onboarding is a vital part to any open source project’s success, and a deliberate approach to these principles should net positive gains for your community. The “if you build it they will come” approach could work, but for more assured participation, the fewer barriers to entry there are to being a part of a community, the faster that community should grow.

Look at your community’s onboarding processes as objectively as you can. Better yet, ask an outsider you know to visit your community and see how easy or hard it is for them to start contributing. Having an independent view of your project’s onboarding is invaluable information that you can use to make your onboarding processes better.