How to Become a Better Open Source Maintainer

Hi friends 👋,

I've been an open source contributor for a few years now. And I love and enjoy the open source collaboration culture. As a contributor, I used to wonder what a maintainer does. How can they keep up with issues and pull requests, especially during Hacktoberfest? What took them so long to review and merge my PR? And there were many other thoughts and questions in my mind.

Since last September, I have had the opportunity to be an open source project maintainer. I help maintain some project repositories at Virtual Coffee, OpenSauced, and SheSharp communities. And now, I can see the view from a different perspective.

Although it was not so long ago that I became a maintainer, I learned so much from this journey. And I keep learning to be a better maintainer through my fabulous teams and mentors. I will share what it takes to be a better open source maintainer in this article.

Communication

Most conversations in open source happen asynchronously. It can be through issues or PR comments, GitHub discussions, or chat services like Discord or Slack. Written communication is prone to misunderstanding, especially in international communities. So good communication in open source is the most essential thing to have.

You want contributors to feel welcomed and keep contributing to your projects. So, improving your communication skills, especially in remote environments, is crucial.

To avoid confusion, take time to answer questions and deliver them in short and clear sentences. Sometimes, there are repeating tasks like asking contributors to resolve conflicts or personally thanking them for their contribution. Having a clear and friendly template ready in the "Saved reply" feature on GitHub is one of the time savers.

However, communication is not always with contributors. When you are part of a maintainers team, you must establish good communication, too. Communicate in which direction the project will go, what the team expects from each other, how the team wants to handle and merge a PR, etc., so everyone can be on the same line. When there is no good communication between maintainers, it can affect the contributors and the project itself.

Observation

To be a better maintainer, you need to be observant. Pay attention to what's happening around the project and how you can improve things for contributors and maintainers.

In one of my experiences, my team and I repeatedly gave feedback to resolve merge conflicts on the guestbook repository at OpenSauced. Most of the time, contributors needed to make several attempts until we could merge their PR. Resolving merge conflicts is a daunting task, especially for beginners. Going back and forth to resolve the conflicts would likely discourage them from contributing to any open source project in the future.

We use CLI for this repository. So, besides fixing some things, contributors also have to run a specific command to update a file. And they often miss this particular step, making them go back and forth. I talked to my team about this observation. I also added a section in our README to resolve conflicts in this repository. Since then, we have been able to merge in PRs faster.

Ask Questions

Being a maintainer doesn't mean that you have to know everything. Asking questions or clarifications to contributors or other maintainers is part of being a better maintainer.

I'm part of the community maintainers team at OpenSauced. So I'm more familiar with the community side than the products. I recently helped review a PR for our documentation that is related to the features of one of our products. To give feedback, I had to look at the features closely and test them out. I also asked many questions about the things that still need clarification.

Asking these questions makes me more familiar with our products. And some of those questions ended up enhancing the features.

Set Boundaries

It's fine and even encouraged for maintainers to set boundaries. The earlier, the better. Setting boundaries can prevent you from getting burned out and have balance.

Like contributors, most maintainers volunteer their time to maintain a repository. Sometimes, you have to prioritize your work or personal life before you can respond to a question or review PRs. Tell your team (and contributors) what they can expect from you. For example, if you won't do any maintenance tasks on the weekend or are unavailable during office hours.

Pull Request (PR) Review

Reviewing PRs is not only paying attention to the changes in the PR. But it's also paying attention to the details.

Pull Request (PR) Form

Before you review a PR, look closely at the PR form.

If the project has a PR template, has the contributor completed the form? And if there is no template provided, does it have a description? Is the description clear enough to describe the changes? Does it mention to which issue the PR is referred, and if not, is there any reason the PR isn't related to an issue? When the changes affect UI, are there screenshots or screen recordings to show the difference before and after the changes?

As a maintainer, you want to educate contributors about the importance of providing details in their PR forms. Clear and detailed information can help you a lot in reviewing PRs and benefit contributors in getting their PR reviewed and merged faster.

Test Changes Locally

Have you ever reviewed documentation changes to a README or any Markdown file on GitHub, and the grammar, wordings, and everything looked good, so you merged it in? But afterward, you realized that the format on the page seemed funny. Or you reviewed code changes, and everything looks neat. Then, you tested things live on Netlify Deploy Preview, and everything worked great. But after merging in the PR, it broke the production.

One of the maintainers' biggest tasks is ensuring the changes work as expected. So, you always want to test the changes locally before you merge a PR.

You can use the "Markdown Live Preview" tool to look at the page format of any Markdown files.

For another type of change like code, you want to pull the branch of the PR and test the changes locally to decide if you will merge it in or ask for some more changes to the contributor. If you don't know how to pull a branch to test it locally, read my article "How to fetch a contribution branch to test it locally as an open-source maintainer".

Final Words

Do you have other tips about becoming a better open source maintainer? Share and drop them in the comment below, and let's learn together! 😄

🖼️ Credit cover image: unDraw

Thank you for reading! Last, you can find me on Twitter, Mastodon, and BlueSky. Let's connect! 😊