More than meets the pull request: maintainers talk contributions

Maintaining an Open Source Project: A Balancing Act Between Code and Community

Open source maintainers wear many hats. They’re not just developers; they’re community managers, code reviewers, and long-term custodians of a project. We spoke with three experienced maintainers—Mike Bayer of SQLAlchemy, Thea Flowers of Winterbloom, and Jordan Harband, a TC39 delegate and OpenJS Foundation leader—about the early lessons, the types of contributions they weight differently, and how they cultivate a healthy project.

The Evolution From Eager to Deliberate

For most beginners, the first pull request is an exciting event. But as projects mature, so does the approach to accepting contributions. Thea Flowers describes her early days as both eager and personal. “I had this identity built around my projects,” she explains, which made criticism hard to handle. It was only with more experience that she grew cautious and deliberate, especially about large changes.

“There are a lot of things about your project that aren’t communicated with just the code—assumptions and things like that,” she notes. Now, she prefers to guide contributors through changes, ensuring they fit the overall design. If a contribution belongs outside the project, she looks for small affordances that allow a user to build their own solution instead of adding to the core codebase. As she summarizes, “Some things just don’t fit in the project.”

Jordan Harband’s early experience began with inheriting projects that others relied on. “It felt like having someone hand me the keys to a sports car at 16,” he says. His approach was consequently cautious, driven by an impostor syndrome that made him want to be meticulous. While he is now more confident, he still values a strong test suite as a safety net for change. Although experience has taught him to be more open, his primary concern remains ensuring contributions don’t break down the road.

Mike Bayer offers the longest perspective, having started SQLAlchemy before Git or pull requests existed. In those earlier days, he didn’t grasp that accepting a patch meant he was now responsible for maintaining it indefinitely. “Accepting a feature, especially one that is poorly thought out, means that you now own it,” he warns. Because of this, he recommends a clear project vision and often points to plugin APIs as a practical way to accept new functionality without expanding the core project’s footprint.

Different Strokes for Different Contributions

The maintainers all agree that the size and nature of a contribution demand different levels of review. In a large library like SQLAlchemy, a small code change can have large implications. Bayer says his team asks for detailed issue descriptions before considering code. He explains, “Some people are in a hurry to just give you some code, but the code is the smallest, easiest part. Tests are much harder, and documentation is the most difficult to create.”

Flowers views changes through the lens of false positives—like the risk of causing regressions or the project’s inertia. She easily accepts low-risk changes like documentation: “We can just rollback a change or make another update.” While bug fixes are generally accepted if they are obvious and have a test, larger bug fixes require caution. But feature requests are a different beast entirely. “It’s like building a new shed in your backyard,” she says. “You’ve got to really think about it a bit.” For her, this process involves weighing the end-user benefit against input from principal maintainers to reach a consensus.

Harband applies stricter rules. “It’s not a bug fix unless it comes with a regression test,” he states clearly. For features, he agonizes over the user-facing process, aiming for changes that are as easy this way as possible. “I try to think first about how it can be non-breaking,” he says, to avoid breaking semantic versioning promises. He considers the innovation and separation of concerns when weighing complexity. The goal often is to find what requires the least impact on project stability, even if that means adding features under flags that aren't active by default. When accepting any change, he thinks about the future burden it places on the project: “I can always add documentation if they don’t.”

Bringing Non-Coders Into the Fold

Getting contributions that aren’t strictly code—like documentation, project management, or design—is a crucial part of a healthy community. The strongest tool by far is fostering a welcoming community space. “The best thing you can do to encourage all different kinds of contributions is to have an active community that you engage with,” says Flowers.

She suggests equipping non-coders with accessible tools, such as “edit this” buttons on documentation pages and straightforward test suites. When contributors want to take on project management, the key is empowerment. “Hold their hand for the first couple of times and then empower them as soon as you can,” she advises, focusing on removing barriers rather than piling on restrictions.

Harband relies on searching the codebase for signs of permission. “I try to slap ‘Help Wanted’ labels on as many things as I can,” he says. This gives new people a way into the codebase without needing intuition about the maintainers' intentions. He also sees immense value in delegation, noting that newcomers who don’t understand the code can write the most relatable docs. It’s a skill he leaves to them, but finding these people proves difficult. “I don’t really know how to do that,” he says with a shrug. “They just show up sometimes, and it’s up to me to keep them around.”

Thea found success on social media. She recalls hiring someone for graphic design after “reaching out on Twitter asking for help with the project.” Bayer also pitches in by asking for design help or using X to promote documentation needs. Conversely, he recalls a failed sprint at PyCon because he didn’t anticipate what entry-level programmers were looking for. They wanted to feel the thrill of the race and meet the stars, not sort the nuts and bolts in the pit. He advises organizers to plan based on the expectations of their intended audience, as sprints can end up being built less for the lead maintainer's benefit than expected.

Wanted: More Helpers, Fewer Fixes

The types of contributions that are easy to give are often not the ones that create sustainability in the long run. Harband wants “more of almost everything,” except for frequent and unnecessary dependency updates or poorly-thought-out patches that assume a long-time maintainer made a basic mistake. Yet he feels a paradox—he'd rather receive an overperforming amount of low-value PRs than experience a lack of overall engagement. What he truly values, though, is the person who makes one contribution and stays for the long haul. “It remains a challenge to get… long-term contributions from individuals,” he says, noting the surprise that so few people who seem interested have the time or endurance to stick around.

There is near-universal admiration for contributions that remove code or clean up technical debt. For newcomers, small task automation is also an essential first step, since they spot things maintainers have become blind to. But both Flowers and Harband caution against meaningless contributions, noting “a pull request with nothing but deletions” is valuable, while “removing a single comma” is a waste of time. The content of issues should also hold a certain standard. Flowers says meticulously long, discontinue-formatted bug reports are demoralizing and confusing when they dig into, “everything that is wrong with it. While they may be correct, the way they present the information can be condescending and unhelpful.” Clarity over condescension saves everyone’s time.

Lastly, docs are “crazy helpful,” says Bayer. Though rare, they eagerly welcome contributors to “write sections of documentation.” He sees an especially important missing role: reviewers. “We have some people that help review patches now, and it’s super helpful,” he adds, along with community members who can be patient with newcomers and broaden the user support network.

Shaping Quality Through Process

Quality is not simply about whether a PR runs without errors. The maintainers stress using guidance and tooling to guide contributors toward best practices before a human ever meets them.

“If they don’t have the label, then you may need to read carefully,” says Harband, who turns to multiple forms of documentation to funnel people in. He prescribes a formula for minimizing the human instinct to do things their own way: open templates, codes of conduct, clear CONTRIBUTING.md files, linting, and dynamic integration tests. “You can create a CONTRIBUTING.MD, have a code of conduct, use CI automation,” and allow the machines to do the role of gatekeeping. These effort-based structures ensure nobody takes poor feedback personally, making things feel less combative.

Mike Bayer’s SQLAlchemy relies on the same shared philosophy. With their templates and integration pipelines, they try to communicate standards at multiple levels. While some contributors might not get it “right most of the time, it’s always a good sign when they try.” That’s an important, human acknowledgement: process guides volunteers who are willing, and it builds rapport for future collaboration.

Flowers distinguishes low-quality interventions—random minor edits or information-free issue reports—from a user’s good intentions. She states, “In most cases, individuals interacting with your GitHub repository… are attempting to make a useful contribution.” Maintainers themselves are responsible for supplying the pathways for useful contribution, such as clear issue templates.

A Conclusion for the Novice Maintainer

At the end of the day, successful project growth requires persistence and wise gatekeeping. Harband believes consistency and explicit goal-setting are critical for a single project, reducing friction for users. Bayer reinforces this long view, underscoring that contributions must be fully maintained when the author checks out. “When it breaks, that’s going to be your problem,” he advises.

Flowers closes with some firm but fair wisdom specific to leading maintainers. “Learn to say ‘no’ often and politely, and sometimes assertively.” After all, an open source project is still 'a garden' that the steward must tend.