It’s hard to attract contributors to your FOSS project — especially contributors who are new to open source.

Project maintainers often discuss making their open source projects more beginner-friendly, so they they can attract new contributors and make them feel welcome. But this dialogue often gets trapped in the echo chamber of maintainers themselves. Instead, it needs to involve the other party: the new contributors themselves.

During my short time as an open source contributor, I’ve browsed through tons of projects, and contributed to a few of them as well. In this post, I’ll try to list what appealed to me as a new contributor, and what didn’t. And I’ll use a few projects as case studies.

Tip #1: Label beginner issues appropriately

This is definitely the most important consideration to me as a potential contributor.

Labels make it easier to find issues that can serve as a beach head for a first contribution. If your project doesn’t have these, it significantly raises the bar for contributing to it.

It is very difficult for someone unfamiliar with your codebase to gauge the difficulty of an issue. So a generic label like help wanted isn’t useful enough on its own. Try using more specific labels, such as good first bug, easy, low hanging fruit, etc. to communicate that an issue is easy enough for an initial contribution.

Tip #2: Establish proper contributing guidelines

A well-written Contributing.md can describe the workflow your project’s maintainers expected contributors to follow. This is easy to document, and will save both sides a significant amount of time.

Specify whether the contributor is required to work on a separate branch for each issue, or to squash their commits and rebase their changes before submitting a PR. Try to link to an appropriate tutorials for each of these processes in case the contributor isn’t yet familiar with them.

Tip #3: Document your project’s design, architecture, and directory structure

Having a document that gives a high-level overview of the design and architecture of your project can save both parties a lot of time.

Instead of explaining the same thing over and over again to every new contributor, take note of questions that are frequently and create an FAQ right there on your README.md.

The steepest barrier for most new contributors is navigating dense codebases. Help newcomers find their way by offering a description of your folder structure.

A lot new contributors are junior developers who may not yet know a lot of common architecture and design patters. Create documents that highlight these decisions and the reasoning behind them.

Tip #4: Put in place a clear Code of Conduct

Create a proper Code of Conduct that explicitly states rules within your FOSS community. A lot of new contributors, including me, are scared of being treated badly, or looked down upon while trying to contribute.

Your Code of Conduct that clarifies how to report violations can help folks feel safe. This also entails calling out bad behavior at every step, irrespective of the stature of the person involved, and taking appropriate action.

Tip #5: Create templates for pull requests and issues

A proper issue template can help people better describe the environment required to reproduce a bug. Contributors can then start working on the issue immediately, without needing to gather information from disparate places. This saves time for both parties.

A similar argument can be made for pull request templates. Clearly lay out what’s expected when a contributor submits a PR, including the format of their commit message, test plan, the changes made. This will help with code review as well, saving everyone even more time.

Tip #6: Prioritize responding to pull requests

Being the maintainer of a popular FOSS project is an incredible amount of work. Most people don’t get paid to contribute to FOSS — maintainers and contributors alike. Most maintainers don’t have enough time to review all PRs with the same amount of scrutiny.

Prioritize PRs so contributors can understand beforehand whether or not they can expect to receive feedback for a low priority/easy bug fix.

Tip #7: Welcome all kinds of contributions

Our field has a nasty tendency to look down on non-code translations. Please don’t let your project fall prey to this mentality.

Encourage all kinds of contributions, be they documentation, code, fixing typos, tests — anything at all.

Tip #8: Reward new contributors

If you have the budget, reward new contributors by sending them swag such as stickers or shirts.

If your budget doesn’t permit that, then a simple shoutout or mention in a blogpost or on social media can also go a long way. It’ll make them realize that their contributions — no matter big or small — aren’t overlooked, and that they are valued.

This establishes a feeling of belonging that may inspire them to contribute more.

Kent C. Dodds made a nifty open source specification for this: All Contributors.

A good start can be maintaining a list of contributors on your project website and/or repository.

Lastly, it never hurts to remember that everyone was once a junior developer. At some point, they needed help to get to the level they’re at today.

This simple fact can go a long way in establishing a healthy culture of mentorship within your open source organization. Treating everyone with respect — irrespective of their background — is critical to running a successful open source project.

I tweeted the above a while back, when I was just getting started with contributing to FOSS. But since then, a lot has changed. I’ve finally concluded:

Open source is way more about people than it’ll ever be about code.

P.S. I am trying to create a list of beginner-friendly FOSS projects. If your open source project has any material relevant to new contributors, please consider opening an issue on this repository.

A shout out to Dan Abramov, Kent C. Dodds and Quincy Larson for helping me with this piece by providing their perspectives as maintainers. 😄

If you have any further tips to add to this post, feel free to reach out to me or reply below.

And if you found it useful, please tap or click “︎❤” to help to promote this piece to others.