It started out as this fun, little hack, tickling your own fancies. You chipped away at it on weekends and in the evenings. Eventually, you sculpted it into a respectable shape. You were rightfully proud of it, so you did a kind deed and shared your creation with the world.
Now, your curiosity has taken you elsewhere, or you’re busy with other facets of your life. But concurrently, your Free / Open Source project has become popular. It’s a hit! The canonical solution to frondubling within the Marnostacean community. And users are filing issues. And sending pull requests that require your review. And building Serious Software that depends critically on your project.
All this activity is so flattering, but it is also so stressful. You’re overjoyed that people like your project as much as you did — that’s why you shared it. But at the same time you feel the weight of all this social pressure on your shoulders to do more work for free. Yes, this is work now: you’ve mostly finished tickling your own fancies, and now you’re fulfilling your users’ desires.
GitHub notification emails sit unread in your inbox. You know you need to reply eventually, because that pull request can’t be merged as-is. It needs certain changes, but you haven’t had the time to explain them in enough detail that the contributor will understand. Nor have you found a moment to test that it handles this other subtle edge case properly. So that notification keeps sitting in your inbox, and every time you check your email, you can’t help but see it there. Unread. Waiting for you. Pretty soon its friends are joining the party: more unread notifications, more people who need your attention, all languishing in your inbox.
I’ve been in this situation to varying degrees. Recently, a couple people independently reached out to me in private, expressing similar frustrations. I’ve found a few things that help me alleviate these issues, and I’m happy to share them. I hope that they also help other folks, but everybody and every project is different.
I’m assuming you still care about the project, its community, the larger
ecosystem it lives within, and that you want it to keep chugging along. If
that’s not the case, then I suggest simply adding a notice that the project is
unmaintained to the top of the
README and unsubcribing from further
emails. Optionally, you can add a way for people to privately contact you if
they are interested in taking ownership of the repository, but it is OK not
to. People can fork it and figure it out themselves.
Give Yourself Permission Not to Fix Everything
Are you being paid to maintain this project full time? No? It’s OK then.
If someone wants their pet issue fixed, then they can fix it themselves. Which leads us to…
Make Contributing Easy
Counter-intuitive as it may seem, this helps. The more streamlined the contribution process is, the less involved you have to be in it.
You should have a
CONTRIBUTING.md file that codifies development practices and
provides instructions for getting up and running and making useful
contributions. If you note that “we require a regression test for every bug fix”
CONTRIBUTING.md, then you won’t have to repeat it in every new bug-fix pull
request, won’t have to tell the contributor to go back and add a regression
test, and then won’t have to review the pull request all over again when the
pull request is updated. If you have instructions describing how to add and run
CONTRIBUTING.md, then people won’t need to bother you to figure it
out, and it is more likely you can merge the first iteration, without any
further back and forth.
Be explicit. If you don’t write out what you want in
don’t be surprised when you get contributions that aren’t the way you want
them. People can’t read your mind.
Additionally, more contributors = more potential maintainers.
Make contributing easy, and then make it easy for contributors to become co-maintainers. Someone just sent their second pull request? Looks like they’re invested in the project! Reach out to them and ask them if they want to be a co-maintainer.
I have seen many a project languish because the maintainer is too busy elsewhere, badly needs a hand with maintenance, but isn’t asking for it. Once they finally declare maintenance bankruptcy, it turns out there were tons of people watching from the sidelines who were willing to help out the whole time, but weren’t sure that their help was wanted. All they needed was that tiny push of being asked for their help.
If your project has users, then it has potential co-maintainers. But you need to take the initiative and provide the leadership they need to learn how to become leaders themselves.
Have the responsibilities and process of becoming a co-maintainer in your
CONTRIBUTING.md. List the extant co-maintainers, too. This way, it’s clear to
contributors that becoming a maintainer and taking on more responsibility is
possible (which can be very motivating for some people), and maintainers get
their well-deserved credit. This list also doubles nicely as a list of people
who can review pull requests, tying back into codifying the project’s
It doesn’t have to be overly bureaucratic. You can add something simple like
Unsure who you should ask to review your pull request? Try one of our maintainers: * `@fitzgen` * `@gza_genius` * `@AirDishNumeroUno` Want to help maintain this project? Drop a comment <a href="link/to/issue/dedicated/to/maintainership">here!</a>
Use an Issue Template
An inactionable bug report doesn’t help the project, adds notifications (stress) to your inbox, and doesn’t get fixed.
Help issue reporters help you (or whoever else wants to fix the issue), by providing a template for them to fill out. GitHub will pre-populate the new issue form with this template, and the reporter just fills in the blanks. Again, this avoids the back and forth that sucks up more of your time, more of the issue reporter’s time, and fills your inbox with those stressful email notifications.
I think that
bindgen has a pretty good issue template.
When someone files an issue that follows this template, and has a
test case that’s only a couple lines long, I often know how to fix the bug right
off the bat after reading the issue.
If, instead of a
creduced test case, they provide
then I have no idea what might be behind the bug. Worse yet, I don’t even have
their system header, can’t run
creduce myself, and I have no hope of
reproducing the bug locally. It is a waste of everyone’s time.
Reply to Issues and Pull Requests Quickly
Thank the person for filing an issue. Thank them because they are well-meaning and they have gone out of their way to do the project a favor: bugs that no one knows about won’t get fixed. Thank them because they provided steps to reproduce and a test case.
But do not make any promises that you’ll fix the issue yourself! (See “Give Yourself Permission Not to Fix Everything”).
After dropping that comment, mark the email notification read and archive it. Don’t let it keep nagging at you. Get it out of your inbox. Don’t let them build up. It’s OK if you don’t have fully-formed thoughts at this moment. You don’t need to. Whoever wants to fix the issue can dig deeper and investigate further. You just need to get it out of your inbox.
But if you do have just a moment, take the opportunity to quickly triage the issue, mention what submodules might be involved, and add relevant labels like “help wanted”, “good first issue”, “feature”, “needs test case”, “needs steps to reproduce”, or “effort: medium”. This makes it easier for some contributor, who may or may not be you, to come along and fix the issue in the future (see “Make Contributing Easy”).
For pull requests, you can set up a bot like
@highfive to randomly select a reviewer
from your set of co-maintainers for each new pull request. Now you only have to
personally review one out of every N pull requests.
Help people fix it themselves. Help people help you. Turn contributors into co-maintainers. Most importantly, don’t let those notifications build up and stress you out.
Do all this as a precaution before you get stressed and burnt out.
Finally, here are a few other resources that I like: