Become an Effective Open Source Maintainer

What does it take to be a good open source maintainer? I know from personal experience that the skills it requires don’t come naturally to many engineers.

Here are my tips on becoming an effective Open Source Maintainer 👇

1. Be Ready for a lot of Notifications

This is a great tip for first-time maintainers: you will get a lot of messages.

“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.”

‍

2. Make it Easy for Newcomers to get Started

Writing clear and detailed documentation and having issues identified that are suitable for newbies make your community more welcoming– and save time for Maintainers, too.

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.”

‍

3. Be Clear on Documentation. Be Really Clear

It is almost impossible to make your documentation clear enough.

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.

‍

4. Be Kind to Contributors

Remember that these contributors are volunteers, who have chosen to spend their time helping improve your project. Repay their contributions with thoughtfulness.

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.”

‍

5. Encourage Multiple Code Reviews per Pull Request

Code reviews are a magic method to help improve the code and help improve coders’ skill and knowledge. It’s not just about the code author, either– code reviewers frequently learn by reviewing.

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.”

‍

6. Automate Processes

The more that can be done to improve the code and core processes, the less work it is for the maintainers and contributors, and the more they can focus on what they can contribute.

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.

‍

7. Set Clear Expectations on Time Commitments and Update them Accordingly

This is the flip side of “Focus” for the Contributors. If you are a Maintainer, be realistic about what time commitment you can actually make, and meet that commitment. If the situation changes and you have to reduce the time, be upfront about that too.

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.”

Also Published Here.