How to welcome community contributions to your open source project

Greetings! So you’re considering actively recruiting more contributors to your open source project for the first time. That’s great! It can be challenging to get new contributors. In this post I’ll go over how to design the architecture of your project so you keep contributors once you have them. In the next post we’ll talk about attracting new contributors.

Step 1: Use community health files to set new contributors up for success

Community health files are a standard set of files that provide additional context, help, and safety to users or collaborators within your open source project. My colleague Blaine wrote a full piece on community health files, and you can check that out over here.

Step 2: Make a guide to contributing

A guide to contributing is a specific type of community health file that provides a blueprint for new contributors to begin working on your project. Guides to contributing greatly reduce the time between the first time someone encounters your project and their first contribution. A best practice is to name this file something like contributing.md (if your text files are in Markdown) and locate it in the root directory.

Typical elements to include: 

• Development environment details
• Build instructions (if relevant)
• Issue tracker
• Project communications
• Pull request protocol
• Bug protocol
• Documentation
• How to make feature suggestions

Step 3: Include an enforceable code of conduct

Codes of conduct are an important signal to new contributors that disputes are thoughtfully and actively resolved within your project. As a maintainer, codes of conduct help you personally because they give you a clear basis on which you can ask contributors with unproductive attitudes to adjust their behavior. Dealing with contributors who are rude or mean is a significant reason for maintainer burnout, and also a big reason new contributors leave a project. 

A good code of conduct should be enforceable including clear consequences for violating the code, and have guidance on how to report issues and to whom, as the maintainers can’t be everywhere all the time. Like licenses, most projects choose to use or remix existing codes of conduct. Some good template codes include the Citizen Code of Conduct and the Contributor Covenant; Tidelift uses the Contributor Covenant for our own communities.

Step 4: Choose transparent communication tools and practices

It’s important to pick simple tools that contributors can use to collaborate and get help. While communicating in the issue tracker works fine for smaller projects, once you have a larger number of contributors, you often need to consider a weekly meeting, a chat channel, or formal threads for discussion.

Having a regular meeting, an open asynchronous chat, or a formal thread in an issue tracker ensures you remain friendly to new contributors. If most major decisions are made “behind the scenes” it can discourage new contributors because the project direction doesn’t feel clear to them.

Step 5: Give helpful pull request reviews

A good pull request review is more than just a technical review or a thumbs up thumbs down.

Ask yourself the following questions:

• Will the contributor feel thanked for their contribution?
• Will the contributor be able to learn from your pull request review?
• Are you giving helpful advice that is something they can implement to make the code better, if it’s something you want to ultimately merge?
• If the code is something you need to reject, are you giving them a good reason why and suggesting something they can work on?

Step 6: Label beginner issues appropriately

Creating a label for beginner issues in your triage helps people know where to start, and many programs that help you recruit contributors, like Outreachy, will actually require it. Good beginner issues don’t require a large amount of knowledge of the code base. The perfect beginner issue is probably something you could fix in a half hour, but isn’t urgent.

Also, consider setting up non-code issues such as documentation, bug triage, or requests for things like design or promotion. Sometimes these types of issues are easier for new contributors because they don’t require extensive knowledge of the code, and they can help future code contributors begin to find their way around the code base or be a path for non-code contributors to start working on the project. 

Contributors whose skills aren’t exclusively technical can be extremely valuable to a project as it scales, as larger projects need complicated work in other areas like user experience, business operations, and people who can run good meetings. 

Step 7: Thank new contributors

With new contributors, it’s important to start by thanking them sincerely for their contribution and pointing out something that works. It’s tempting to skip right to the part where you fix the code so the request can be merged; and it’s tempting just to reject code that doesn’t fit your purposes.  However, contributors are from many different cultures and have many different levels of frustration tolerance, and so it’s important to err on the side of being kind at first.  

Following these 7 steps will get you well on your way to being welcoming for new contributors! In our future blog posts we will cover how to recruit contributors and more.

If you’d like to learn more about ways you can level up your project into an income-producing product with Tidelift, check out this blog post where we explain the whole process.