Stop Burning Out Maintainers: An Empathetic Guide for Contributors

As a bootcamp grad myself, I can understand that it’s overwhelming to try to break into the industry with so many people giving you advice. I remember being a couple of weeks short of graduating and one of the school's founders telling me to get involved in open source. I felt panicked. Why am I hearing about this for the first time? How do I do that? What does that even mean?

Here’s the thing: contributing to open source isn’t about a checkbox, it’s about building a connection. I think that’s where we get it wrong a lot of times.

There’s recently been a lot of talk about whether or not people should be contributing to open source. I’m not going to talk about that directly, but I’m going to talk about what might cause someone to not want new contributors: burnout.

It’s no surprise that many maintainers are facing burnout. There are a lot of reasons for this, including lack of recognition, loneliness, lack of compensation, high demands, and increasing responsibilities.

“Just keep in mind that my time is finite and if I have to go back and forth on your PR for stuff you could have caught yourself with a second look, you take time away from other PRs” - Sindre Sorhus

If we want a healthy open source ecosystem, we cannot put all the work on maintainers. Contributors have to share the responsibility and be good open source citizens. Maybe right now you’re thinking, “What does that mean?” Well, I’m about to tell you.

Read the Directions

I don’t know about you, but in grade school, there was always that one teacher that would create a quiz with a bunch of directions. At the end of the directions, it would say something like, “As soon as you’re done reading the directions, hand in your quiz.” Half the class would be writing huge essays, and the other half would be turning in their papers. The ones who were still writing were panicked because, How are all those people finished already?!?! The teacher did it to make a point: Read through the directions in their entirety to understand the assignment. Open Source is no different.

• Read the Readme. Do you understand all the steps to get the project running? Have you tried to follow the steps to run the project?
• Read the Contributing.md. Do you understand how to communicate with maintainers? Do you understand your responsibilities as a contributor?
• Read the issue. Have you read it a second time? Have you looked at screenshots, gifs, or videos provided in the issue? Do you understand what the issue is asking? (If you don’t, do not ask to be assigned the issue until you understand.)
• Read the PR template. If you’re to the point of submitting a pull request, make sure you read through each section of the PR template and answer each section.

Any time a maintainer has to give you feedback because you haven’t spent the time to read through all the content they’ve prepared to enable you to succeed in your contribution, you’re contributing to their burnout. Reading directions is not optional.

Check Your Work

It is not the maintainer's job to proofread and check your work. I’m going to say that again: It is not the maintainer's job to proofread and check your work. It is your job to make sure your work, well, works. Ask yourself:

• [ ] Can I run this locally without errors?
• [ ] Have I manually tested it?
• [ ] Have I addressed everything that’s asked for in the issue?
• [ ] Have I run tests (if applicable)?
• [ ] Does the build work in GitHub?

Any time a maintainer has to give you feedback because you haven’t spent the time to check your work, you’re contributing to their burnout. Checking your work is not optional.

Be a Problem Solver

I have four kids. When they get stuck on a problem, I tell them, “Be a problem-solver. What can you do to figure this out?” Sometimes they cry, sometimes they yell, and sometimes they succeed. I know that sometimes it’s impossible to figure it out on your own, but there are plenty of times that it’s growing pains. You have to push yourself and believe that you can solve the problem. If you’re stuck, before you ask for help, ask yourself:

• [ ] Have I read the error messages?
• [ ] Have I spent time understanding the problem? (A good indication that you understand the problem is if you can explain the error, why you think it’s happening, some possible solutions, and what you’ve tried.)
• [ ] Have I checked for typos
• [ ] Have I googled the error messages?
• [ ] What have I tried to do?
• [ ] Have I read the documentation?
• [ ] Have I looked at other issues in GitHub that address a similar problem?
• [ ] Have I debugged the error message?

Do the Work

I taught college English for ten years. When I assigned a student a paper, I expected them to do the work. I pushed them to work hard, improve, and think deeply about what they were putting on paper. I don’t think that’s too much to ask from contributors. This isn’t to say, don’t ask for help. But ask to take on issues that you think you can handle. If you can’t, then ask for help from the community, your support system, or the maintainers. But remember, they shouldn’t be solving the problem for you. They should be directing you towards the correct solution.

If you’re asking them to do the work for you, you’re not going to grow. To be transparent, if you’re frequently taking on issues and asking other people to solve the problems for you, the maintainers will notice. Not only does that impact your reputation, but it damages your relationship with them.

Any time a maintainer has to give you feedback because you haven’t spent the time to problem solve, you’re contributing to their burnout. Problem-solving is not optional.

Communicate Appropriately

This is a big one. The Contributing guide usually talks about how you should communicate with the maintainers. If it doesn’t, at the very least, you should assume that within the PR, issue, or in their communication platform public channels (like Discord) are the designated communication spaces.

It’s best practice to not:

• Direct message a maintainer.
• Ask a maintainer to review your PR or issue outside of GitHub (for example, in a livestream, X Space, or during an event).
• Ask a maintainer for a review if you know they’re out of the office (including on vacation, on the weekends, etc.). It’s worth noting that if you know they’re on vacation, you probably shouldn’t ask them on their first day back. They’re getting caught up, and any attention they take away from catching up to respond to you, is time they have to make up.

It is best practice to:

• Accept feedback willingly.
• Listen to maintainers.
• Communicate with empathy, this includes not only being kind, but also being patient.
• Actively listen.

Ok, so that last one might feel out of place when communication takes place asynchronously. What I mean by that is to take the time to holistically understand what a maintainer is asking you to do. If they have a comment on your PR that applies to the whole PR, don’t fix it in one place and force the maintainer to come back to provide you with the same feedback in every place.

Communicate Clearly

Here’s a checklist:

• [ ] Write clear titles (for PRs, discussions, and issues)
• [ ] Provide screenshots or gifs to demonstrate problems or fixes
• [ ] Complete Issue forms or PR templates. Do not skip any of the required fields.
• [ ] Be specific in your descriptions, bug reports, and PRs.
• [ ] If you’re stuck, have you clearly outlined the problem, what you’ve tried, and shared any relevant code?

Another part of appropriate communication is how you ask for things from a maintainer. Open source projects aren’t for making demands.

Do Not Make Demands

Second of all, it’s not ever ok. There are people maintaining projects, and unless you’ve funded them for life, you have no right to make demands. You’re welcome to propose a fix or a feature, but the maintainers are in charge of prioritizing.

Any time a maintainer has to address your response outside of the appropriate space or has to ask you follow-up questions because you haven’t provided the full context of your issue, you’re contributing to their burnout. Appropriate and good communication is not optional.

Takeaways

90% of companies are applying or using open source software in some way. We’re all in this together to create a stable and healthy open source environment. This post is not to point fingers at anyone. It’s to ensure that we all learn how to support each other in meaningful, productive, and empathetic ways. Part of ensuring that we can have a healthy open source environment is being a thoughtful contributor and good open source citizen. It’s on all of us to ensure open source maintainers don’t burn out.