The Maintainer Is the Interface - Kenneth Reitz

Skip to content

Essays

People assume the interface of an open source project is the API surface. The README. The documentation. The function signatures and the error messages and the way import requests just works.

For the person who has never contributed to your project before, the first real interface is none of those things. It's you. An issue response. A PR review. A one-line comment on a first contribution.

The maintainer is the interface. And unlike an API, this interface speaks back. It has moods. It has bad days. It can make you feel like you don't belong.

I've made mistakes in my dealings with open source. On projects like Requests and Pipenv, I got some things right and some things wrong, over the years. This essay is about what I learned.

The First Response Is the Onboarding Experience

Think about the last time you opened a pull request on a project you'd never contributed to. You probably spent hours on it. You read the contributing guide. You ran the tests. You wrote the commit message carefully. And then you submitted it and waited.

That waiting is the most psychologically loaded moment in open source contribution.The median time to first response on a GitHub PR is measured in days. For the contributor, those days feel like standing at someone's door after knocking, not knowing if anyone is home. You've put yourself out there. You've said, implicitly: I think I have something to offer to this project. The maintainer's response is the project's answer to that implicit question.

A fast, thoughtful response that acknowledges the effort and engages with the substance makes the contributor feel welcomed and capable. It says: yes, you belong here. Your effort was seen. Even if the code needs changes, the person behind the code was received with respect.

A terse "this doesn't match the style guide" makes them feel judged.I've seen first-time contributors delete their GitHub accounts after receiving terse rejections. The cost of a cold response is not measured in the maintainer's time saved. It's measured in the contributors who never come back. Not because the feedback is wrong. The code probably doesn't match the style guide. But feedback without warmth is evaluation without relationship, and evaluation without relationship feels like rejection to the subconscious mind. The contributor doesn't think "I should fix the formatting." They think "I shouldn't have tried."

Both responses are technically valid. Only one produces a returning contributor.

from dataclasses import dataclass

@dataclass<br>class FirstContribution:<br>"""The moment that determines everything."""

effort_hours: float<br>vulnerability: float<br>response_warmth: float<br>response_days: int

@property<br>def returns(self) -> bool:<br>"""Whether the contributor comes back.

The quality of their code barely factors in.<br>What matters is how the interaction felt.<br>"""<br>return self.response_warmth > 0.5

People don't leave projects because the code is hard. They leave because the experience of participating felt unwelcoming. The maintainer's communication patterns are the project's onboarding experience, whether the maintainer designed them that way or not.

The API of Human Interaction

Interfaces shape what feels possible, not just what is possible. A project with a welcoming maintainer feels like a place you belong. A project with a hostile maintainer feels like a place you're trespassing. The subconscious makes that assessment before you've read a single line of code.

Good API design and good maintainer behavior follow the same principles. Not because human interaction is "like" an API. Because both are interfaces between minds.

Sensible defaults correspond to assuming good faith. When someone opens an issue or submits a PR, the default assumption should be that they're trying to help. Not that they're wasting your time. Not that they haven't read the docs. An API that assumes the developer knows what they're doing and provides helpful fallbacks for when they don't. A maintainer that assumes the contributor is acting in good faith and provides gentle correction when they're not. Same principle, different substrate.

Error messages that help correspond to PR reviews that teach. I wrote in Designing for the Worst Day that "Invalid input" is an accusation while "Did you mean..." is a hand extended. The same distinction applies to code review. "This is wrong" is an accusation. "Have you considered this approach? Here's why it might work better" is a hand extended. Both communicate the same technical information. Only one leaves the contributor feeling competent enough to try again.

Graceful degradation corresponds to patience with imperfect contributions. A well-designed system doesn't crash when it receives unexpected input. It degrades gracefully, handling what it can and providing useful feedback about what it can't. A good maintainer does the same with imperfect pull requests. The code might...