DEV Community

Cover image for How to Become a Better Open Source Maintainer
Ayu Adiati
Ayu Adiati

Posted on • Originally published at adiati.com

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! ๐Ÿ˜Š

Top comments (8)

Collapse
 
eminaltan profile image
Emin Altan

Hi Ayu I want to become contributer. But where can I start and how can I find project on GitHub

Can you help me as a mentor? Thanks

Collapse
 
adiatiayu profile image
Ayu Adiati

I highly recommend the Intro to Open Source with @saucedopen.

And this article, A Complete Guide to Getting Started in Open Source by @bekahhw to get you started! ๐Ÿ˜„

Collapse
 
eminaltan profile image
Emin Altan

Thanks Ayu ๐Ÿ™ I will check it out

Thread Thread
 
adiatiayu profile image
Ayu Adiati

You're welcome! And feel free to reach out anytime you need! ๐Ÿ˜Š

Collapse
 
felixdev9 profile image
Felix

Love the series and the work you've been doing.

Collapse
 
adiatiayu profile image
Ayu Adiati

Thank you! ๐Ÿ™‚

Collapse
 
raguay profile image
Richard Guay • Edited

My problem is that none of my open source projects has anyone contributing to them. It's just me. I guess my projects are too tailored to my own needs to be used by many. With my time to work on them being so small, they would progress faster if I had some help. If anyone is interested, my projects are:

These are stable applications that I use daily:
EmailIt (GitHub.com/raguay/EmailIt)
BullitenBoard (github.com/raguay/BulletinBoard)
ScriptBar (GitHub.com/raguay/scriptbarapp)
Modal File Manager (github.com/raguay/ModalFileManager)

This one is very pre-alpha, but fun to work on:
Personal Kanban (github.com/raguay/PersonKanban)

Collapse
 
adiatiayu profile image
Ayu Adiati

Have you tried to promote your project here, on DEV, or social media like Twitter or LinkedIn, @raguay?

You can write a short blog post to introduce your projects and attract contributors, and share the post on socials.

You can also create and use good first issue label on your issues that can be handled by beginners.

Alternatively, you can create a profile and Highlights at OpenSauced by @saucedopen to highlight issues and PRs of your projects. That way, they will be visible to contributors and maintainers in open source.

You can also join their community on Discord.

Another open source communities that I recommend is EddieHub.

Hopefully it helps and wishing you all the best! ๐Ÿ˜„