How can a project maintainer help newcomers feel more comfortable and confident about making their first contribution? This post has a few protips for making your open source project a welcoming and safe environment for newbies.

Every now and then we hear people confessing they would love to get more into open source, but they feel afraid – there are just so many things that could go wrong! What if I’m not good enough? What if I get strong criticism on my pull request? What if I break all the things? What if the issues are way too complex / hard for me?

As an active open source contributor, I can relate to all these feelings so well – I remember how hard it was to get my first pull request out there. Making a first contribution can be super challenging for a newcomer, considering all the parts involved: more than the code itself, there’s also the whole process of Git/GitHub flow, branches, versions, etc… and, of course, the code review – the scariest part of all.

How can a project maintainer help newcomers feel more comfortable and confident about making their first contribution? This post has a few protips for making your open source project a welcoming and safe environment for newbies.

Have Good Documentation

Documentation is the first thing anyone will look for in a project, and a user needs to understand what is going on before contributing to your project. If your documentation is incomplete, it might happen that a user considers contributing with a feature that is already there, but you forgot to document. Good documentation should be a mantra for any open source project since day zero. It doesn’t need to be perfect or 100% complete – you can ask contributors to help with that later. Just make sure you cover the most important parts and do it well – also, it’s important to explain how to run your project in case it’s an application, or how to set up an environment for it.

This post from Charlotte Spencer has some excellent protips for writing good documentation that is friendly for newcomers.

Have Clear Guidelines in a “Contributing” Doc

The “Contributing” doc should be the official resource where newcomers can find information about contribution guidelines, like which branch users should base their code and submit pull requests to, which code standards you have defined for the project and other important information users should be aware of before starting to work on any issue.

It’s always a good idea to provide a way of contacting the project maintainers, and encourage contributors to have an open communication since the very start – you don’t want people wasting time on implementations that most likely won’t get accepted. Gitter is an excellent tool for that – you can easily create a web chat room for any project hosted on GitHub. To join the chat, users just need to log in with Github.

Let People Know They are Welcome

From my previous experiences, I believe most open source projects are very welcoming to new people – only project maintainers know how hard it is to get contributions (and how much work is still to be done), so any contribution is valid. However, this might not look obvious for people who come to your project’s repository page.  Make sure to let people know that newcomers are welcome and all contributions matter!

Let People Know They can Contribute in Different Ways

There’s much more than code to be done in an open source project – documentation, demos, website, logo… Let people know the different ways they can help, and once more, let them know that all contributions are valuable contributions.

Tag Your Issues

Tagged issues look much more organized and make it possible for a user to filter the issues that might be more suitable for their expertise. This is great not only for newcomers, but also for your general project organization.

Create Easy-Pick Issues

Having “easy-pick” issues is one of the best things you can do for helping newbies getting around and making their first contribution. There’s always room for easy, simpler issues. If you think you don’t have easy picks, have a look again and try to break down a big issue into smaller ones. Be very specific if you can. Describe in detail what you would like to accomplish or fix, and maybe give a lead on where or what to look for.

When you have tagged easy picks in your issues, don’t forget to share them with YourFirstPR – an awesome project aimed at helping first-time contributors to get their first pull request done.

If you want to go even further, consider getting some issues tagged as first-timers only, an idea proposed by Kent C. Dodds in his post “First Timers Only“.

Consider Having a Code of Conduct

When you are the only maintainer and contributor of a project, you are most likely the only person who will comment on issues and provide feedback on code reviews. You are a nice person, aren’t you? I’m sure you won’t discriminate contributors  based on their gender or race, or make mean comments on their pull requests. But what happens when the project starts to get bigger, and you have no control over the people commenting and reviewing code? Have you thought about that?

Bigger projects are proven to be much scarier for newcomers, since so many eyes will be over your pull request. Who are those people? Are they friendly? Will they be nice if I make a mistake?

Having a Code of Conduct help setting expectations and what is or is not acceptable in terms of behavior for contributors. It makes people accountable. It’s a way of telling newcomers that you care about how contributors behave, and that you won’t tolerate discrimination / humiliation attempts in your project.

Be Nice!

At the end of the day, what makes a project friendly is the people who maintain it, the ones who reply to issues and perform code reviews. You are not obligated to accept any and all pull requests, and you are entitled to reject any contribution that doesn’t look good enough or doesn’t comply with the project’s guidelines. But no matter what, be nice! There are many different ways to provide feedback, and there’s always a nice way of doing so. Exercise your empathy. Place yourself in that other person’s shoes. Any pull request should be treated with respect and gratitude – that person dedicated their time to propose a change that, in their eyes, would make your project better. It’s a gift. Be respectful.