Elevating open source contributors to open source maintainers

Maintaining an open source project is a lot of work. You have to write features, respond to issues, review pull requests, moderate community discussions, write documentation, and more. Bringing in co-maintainers can help prevent burnout by offering fresh perspectives and making a project more fun and collaborative. But giving administrative access to your repository is intimidating. It’s something you really only want to give to someone who is trustworthy, understands the vision for your project, and will stick around long enough to make a difference. Where do you find such people?

One time-honored way is to elevate your existing contributors into full-fledged maintainers. This month, The ReadME Project Senior Editor Klint Finley spoke with three experienced maintainers about how they identify, onboard, and collaborate with co-maintainers.

Carol Willing is the VP of Engineering at Noteable, a three-time Python Steering Council member, a Python Core Developer, PSF Fellow, and a Project Jupyter core contributor. She’s also a leader in open science and open source governance, and is driven to make open science accessible through open tools and learning materials.

Brandon Roberts is an open source software advocate. He is a Google Developer Expert for Angular, a maintainer of the NgRx project, creator of the Analog meta-framework, and Head of Engineering at OpenSauced.

Paulus Schoutsen is the founder of Home Assistant and Nabu Casa. His work revolves around building the “Open Home”: his vision of a smart home that offers privacy, choice, and durability.

Klint: How do you identify contributors that would be good co-maintainers? What are the signs of someone ready and willing to step up?

Carol: At Project Jupyter we run a regular cronjob to find active contributors. We regularly reach out to those folks and ask if they want a more active role. If they do, we coach them informally on how to be a maintainer, how to review pull requests, and things like that. We tend to be pretty liberal about giving people merge access. It’s more about trusting that someone will follow the project’s direction rather than trusting them not to make errors. It’s about how they engage and whether they will make the project better in the long term.

For a larger project like Python, we have a more formal structure. The first step is joining the triage team, which helps prioritize issues but doesn’t merge pull requests. We mentor active, engaged triage team members and eventually give many of them full merge permission. When someone is made a core contributor to Python, there’s usually a month-long process where the mentor oversees the work.

Brandon: I was a contributor to NgRx before I became a co-maintainer. I just jumped in and started looking at issues and solving problems. If you do that consistently over time, maintainers will see you as a solid contributor. I look for people that take this level of initiative. It also matters how you interact with other contributors or people who want to contribute. When I notice someone who is helping out with issues and actively investing time into a project, I invite them behind the curtain, so to speak, to give them more insight into the decision-making process and offer an opportunity to have more influence on the project.

Paulus: I used to be of the “give merge access early and often” school of thought, but Home Assistant is too big for that now. Still, even at our size, a social connection is important. Co-maintainers need to see you as a peer. For that, you need to create a community. We started with GitHub Issues, but that’s not really a tool for building community. Then we tried a mailing list, then a forum. What we found that worked best for us is chat. It’s a good place to meet contributors and see how they interact with the rest of the community. It gives you a chance to see not just the quality of their contributions but how they deal with people who have different opinions.

Klint: How do you encourage someone who would clearly be a good maintainer but is worried that they are not qualified?

Brandon: If they have reservations, I would point out that they’re already doing the work. That’s the whole reason I’m asking them.

People think the leap from contributor to maintainer is a grand thing, but you continue to do the same things you did before but as an official representative of the project. You also have more say in what happens and the direction we go.

Luckily, all the people I’ve asked to become maintainers have been excited to join the team. But sometimes people need a little more encouragement when you ask them to step into an unfamiliar domain. I tell people to trust the process and not count themselves out just because they don’t think they have the right experience or skill set.

Paulus: It hasn’t been a huge issue for us either. If they’re already an active contributor, they tend to know what to expect. Also, we have something like 100 maintainers. It would probably be more pressure if you were the third maintainer. You can invite people to a GitHub organization without giving them commit access, so that’s a low-pressure way to get someone more involved.

Carol: I see this fairly often, when contributors are worried they either don’t have the technical abilities to be a maintainer or think it will be too much responsibility. How I respond depends on their concerns. It starts with a conversation.

For people who are worried about the technical side, I emphasize that on a large project, no maintainer really understands the whole code base. I remind people that we all make mistakes and if something goes really wrong we can always revert changes.

As far as the responsibility and time commitment, like Brandon, I emphasize that people are already contributing to the project. Becoming a maintainer is less about committing more time to the project and more about committing to the project long-term. Of course, things come up in people’s lives and they need to take on a less active role and that’s fine. Project Jupyter has a “Red Team” of maintainers who are typically more active, and a “Blue Team” that is less active. Being able to switch between the two teams gives people permission to pause and contribute when they can without feeling like they’ve abandoned the project. It helps us avoid losing maintainers to burnout.

Klint: How do you onboard new maintainers? What do they need to know that they didn’t likely already know?

Brandon: We invite them into our private chat channels where we have more focused conversations. We share our internal documentation. There’s a fair amount of administrative work, adding them to things, sending them calendar invites. It’s a bit like onboarding someone to a new job.

Paulus: We have plenty of documentation about how we do things. We also use a lot of automation, like linters and formatters, which takes much of the pressure off manual reviews. No one wants to reject a pull request someone spent hours on because they missed a comma or something.

Carol: At Jupyter, we have a template that can be used by any of our groups. It covers the project’s history, its current direction, who to contact to get involved in different aspects of the project, and each maintainer’s current Red Team/Blue Team status. We call it the “Team Compass” because it helps keep people moving in the same direction.

Klint: How do you resolve disputes with other maintainers?

Brandon: We’ve had differences of opinion on things, but those conversations have been pretty chill. I wouldn’t call them disputes, we keep them conversational. Sometimes we punt things because they might cause us friction as maintainers. We often end up with more information that helps us make an informed decision and avoid heated discussions.

Carol: First and foremost, we try to keep it to the technical stuff and avoid getting personal. It’s important to model the behaviors you want to see from the rest of the community. I try to understand a person’s perspective. What’s driving them? The real trouble starts when you play favorites or make people feel like they’re not being heard. I look for context and try to build a win-win situation. We often think of things as binary, when in reality there is a spectrum of possibilities. Sometimes a decision is a one-way door, but a lot of times you say “Let’s move ahead this way, and then reevaluate in 30 days.” That lets you keep the conversation going without blocking the project.

Paulus: Most of the disputes we have are about project rules and processes. Step one is to make sure discussions are happening in the right place. A pull request isn’t the right place to have a conversation about changing our rules. It would be better to have the conversation on Discord, where it’s more visible. We document why different rules are in place and why past decisions were made so we can point to them when issues arise. Sometimes, showing someone the “why” is enough to settle a debate. After an initial discussion, we might start a formal process for changing a rule. Going through a process slows things down, which is actually good. It gives people a chance to cool off.

Klint: Have you ever had anything go so wrong that you had to remove another maintainer from a project?

Paulus: We had one incident many years ago. There was a good front-end contributor who had a short temper and would get angry with users just for requesting something. That doesn’t work. We tried to calm him down, but we eventually had to let him go. I think this was the only time we had a maintainer break our Code of Conduct. We haven’t had to ask someone to leave because of their technical contributions.

Brandon: Although we’ve never had to remove anyone from our team, there was an instance where we attempted to collaborate with an individual on a project, but it did not work out. Their ideas were good, but they weren’t a fit for the maturity level of our project. They moved forward and started a new project with those ideas and carved out their own space, which worked out better for everyone.

Carol: Unfortunately, yes, we have. Removing someone is the last resort. Usually, it’s because they’ve repeatedly crossed a line. We give people many chances to correct their behavior. Sometimes they do and there’s no further issue. But other times we see a pattern of increasingly bad behavior. You have to look at what the person is going through. Sometimes people just need a break from the project. But ultimately you can’t jeopardize the sustainability of the project for one person who is not acting professionally or in the project’s best interest. It’s not a fun process. You never want to say “Please leave,” but sometimes it’s better to say “Please leave” than have the whole project suffer and become a toxic environment.

Klint: Sometimes it’s hard to let go and let others step in. Do you have any tips or best practices for delegating tasks to other maintainers?

Brandon: I used to feel like I had to come up with all the ideas and execute them myself. But once you have other people on the team, you can share the ideas and let other people run with them if you don’t have the bandwidth. My fellow maintainers often have their own ideas about how to help out, and I encourage them to share them so others can do the same.

Paulus: I don’t write much code anymore, I mostly manage projects. We’re in an unusual position because we integrate with lots of different hardware. We have to deal with firmware and microcontrollers and build software bridges between different devices. It requires a lot of people with different areas of expertise. I couldn’t do it all even if I wanted to. The best successes we have usually come when I create small project teams. For example, I might say “Let’s do something about music,” and pull in people from different areas, and then help coordinate different activities. If you’re having trouble letting go, consider the areas where other people have more expertise and ask people to pitch in there.

Carol: If you’re worried about someone making mistakes, remember that everyone makes mistakes, including you. Don’t hold someone to a higher standard than you hold yourself to. Tasks you’ve been putting off are often good learning opportunities for other people. They can do the leg work, and you can supervise, it’s a win-win. I think it’s helpful to have processes and guidelines for best practices when triaging. That way, people know where to look for things to do, and understand what is expected of them.

Do you have a burning question about Git, GitHub, or open source software development? Drop your question to us on your social channel of choice using #askRMP, and it may be answered by a panel of experts in an upcoming newsletter or a future episode of The ReadME Podcast!

Want to get The ReadME Project right in your inbox? Sign up for our newsletter to receive new stories, best practices, and opinions developed for The ReadME Project, as well as great listens and reads from around the community.

Written by

Klint Finley

@klintron