Notes on maintainer burnout — Kristof Kowalski

I maintain a small Go library that crossed ten thousand stars sometime in 2023. It was the first project I’d ever run that required my attention every single week. Here’s what I learned, mostly the hard way.

The work isn’t the code

The code is maybe ten percent of maintaining a popular library. The rest is:

Triage: reading 30–50 issues a week, deciding what’s a real bug
Review: shepherding PRs, asking for tests, closing the ones that have gone cold
Communication: explaining decisions in public, sometimes to people who disagree loudly
Releases: the actual mechanical work of cutting a version, writing the changelog, dealing with the downstream breakage you didn’t anticipate

The first time I went on holiday for two weeks I came back to 180 unread issues. The third time I went on holiday, I’d handed the project to a co-maintainer.

Patterns that helped

A weekly office hour. Half an hour on a Friday, public, video off. It triage-shifted a lot of issues — people who would have filed a ticket instead just asked in the call. The ticket is more expensive than the question, for both sides.

A CONTRIBUTING.md that explains when to file an issue. The single highest- leverage change I made was adding a line that said “If you’re not sure whether something is a bug, ask in Discussions first.” Issue count dropped by a third.

A real README that includes a “this is not for you” section. The most useful thing I ever wrote was the section that said “if you need X, use library Y instead.” It told people I’d thought about their problem. Half of them went away happy.

Bot for stale-issue closing. A 30-day ping for “still relevant?” that auto-closes after another 30 days. Sounds harsh, but every maintainer I know who runs one says it changed their life.

Patterns I wish I’d started earlier

A SECURITY.md that points to a private reporting channel. I was reporting my own security email in issues for the first year.
A maintainers’ group chat — even a 3-person DM thread — for “should we revert this?” moments. Don’t make those calls alone.
An explicit succession plan, written down. Not because you’re leaving, but because writing it down forces you to think about what a project without you looks like.

The thing nobody tells you

Open-source maintainership is a job. Not in the sense that anyone is paying you, but in the sense that the work has the same shape as a job: it accumulates, it has deadlines you can’t see, and if you don’t set boundaries it will consume all of your time.

You can love the project and still need to step away from it. That’s not burnout, that’s maturity.