How can you be an effective Open Source Maintainer?

In our previous blog post, we shared some tips on how to be an effective Contributor to Open Source.

Now let’s talk about tips to be an effective Maintainer. There are seven tips here too. I promise that was a coincidence.‍

Be ready for a lot of notifications

“Be prepared for lots of notifications. It can be a bit of a shock, especially if like a really enthusiastic person comes across your repository and makes a lot of issues or pull requests at one time. This is a good thing and it means that people are learning all the time. So go with it.”‍

Make it easy for newcomers to get started

Here are Maintainers on how to do this well:

“At EddieHub, we have a ‘good first issue’ channel, where people can pick up good first issues to get started. However, for people who are posting those links, just make sure they are good first issues, make sure they have steps for people to understand how they need to get going.”

“Make sure that your Readme has a really good quickstart guide so people can get started. It’s not just about how you clone a repo, there are many official sources for that. Make sure that you also cover the specific parts about your project in your repo rather than the stuff that people are going to find on finding the official documentation.”‍

Be clear on documentation. Be really clear

One maintainer: “Make sure you have like a really clear contributor files, saying like, if you want people to, for example, write the pull requests in a specific way, have it clearly explained in the contributor file so that people know how to contribute. And then there’ll be less back and forth.”

Pro Tip 1: Read your documentation out loud. Is it something you would say to another person? If not, change it to how you would say it.

Pro Tip 2: a great project suitable for new contributors is to have them pressure test your documentation. Have multiple newcomers read the documentation and see what questions they have. Then update the documentation to reflect answers to those questions.‍

Be kind to contributors

This does NOT mean that you will always agree with their contributions- after all, a reason to contribute to Open Source is to get feedback to become a better coder or technologist — but share feedback through code reviews or other methods with a spirit of generosity.

Another maintainer: “Be kind to the people that want to contribute to your repository. Even if they do something wrong, it’s not out of ill will, they’re there because they want to contribute. Many of them are young, try to help them learn. And just try to be as kind as you possibly can. Because it’s easy to take things the wrong way in like a written message when you write back to someone in an issue or a pull request.”‍

Encourage multiple code reviews per pull request

And while one code review is good, two or three code reviewers can be even better.

One maintainer: “It’s always great to have multiple reviews. Pull requests with two or three reviews means there was a great (asynchronous) conversation and coordination, which helps the project.”‍

Automate processes

One maintainer: “I would say automate as much as possible. So have if you’ve got linters, run them on GitHub actions. Not to take away from the collaboration or communication that you’re gonna do with the community, but focus that collaboration and communication on what matters more. There’s no point are we saying you’re missing a semicolon, your indentation is incorrect, you want to have that automated, and then you can discuss the more interesting and fun things.”

Pro tip: helping automate tooling for a community is another great way to contribute, whether that’s in the codebase or in the communication channels.‍

Set clear expectations on time commitments and update them accordingly

As a Maintainer, people are now relying on you, and it’s much better to underpromise and overdeliver than having people wonder where you went.

One maintainer: “Don’t stress yourself out by thinking I have to dedicate many, many hours to this every week, because I’ve volunteered to be a maintainer. If you’re looking to be a maintainer on a certain site, and you don’t feel like you’re going to have the time, discuss that with the person that owns the repo in that case, just so that you don’t feel stressed yourself.”‍

Originally published at



The blog of Sema.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store