Skip to content
Frances Coronel

Artwork: Micha Huigen

ONWARD: A framework for maintaining maintainers

Whether the project has 3 or 3000 contributors, here’s what to focus on when collaborating with other maintainers.

Photo of Frances Coronel
Byteboard logo

Frances Coronel // Senior Software Engineer, Byteboard

The ReadME Project amplifies the voices of the open source community: the maintainers, developers, and teams whose contributions move the world forward every day.

Also in Developer Stories

Great leaders create more leaders

I started on GitHub as a passive lurker, casually starring or watching projects that interested me. After about a year, I started publishing small side projects on to GitHub. Then, after about another year, some of those side projects got a bit of traction and I dedicated more time to maintaining them by myself. 

Eventually, I graduated to the big leagues—contributing to projects led by a group of dedicated maintainers. These were projects that many people were involved in or depended on, and the stakes got higher!

One of my earliest pull requests (PRs) to such a repository (repo) was for freeCodeCamp, a nonprofit dedicated to providing accessible coding education. To this day, they remain one of the most popular and active projects on GitHub. Since their community was immense and thriving, I had the opportunity to attend a few local meetups. I was ready to participate more actively. I started opening PRs for their “guides” repo, where they hosted documentation about various technical topics.

Thankfully, the maintainers for this repo were very welcoming. I continued to participate as an active member in the community to the point where I contributed to their blog, spoke at a local meetup, and became a maintainer of one of their repos.

As I started to focus more on my full-time job, I began promoting contributors to maintainers for my side projects while becoming the lead maintainer for a larger open source project for a nonprofit. I even got awarded and funded for my open source work and invited to speak about my experience at different events.

From my humble beginnings as a lurker on GitHub to being awarded for my open source work, I’ve developed a framework called “ONWARD,” outlining what I recommend maintainers should focus on when collaborating on a project with other maintainers, regardless of whether they have 3 or 3,000 contributors. 

O is for Open

You can’t be a maintainer of an open source project without embodying the value of being open yourself! 

That means being open to feedback, discussions, guiding others, significant changes, and even ownership. 

If you inadvertently become a single point of failure when things get hairy, you’re not being open enough with your knowledge or power within the project. It can also imply you need extra support, starting with creating an environment where that’s possible.

Below are some examples of how you can embody this value of being open as a maintainer in practice:

  • Have an accessible space for discussions and feedback

  • Document as much of the knowledge in your head as possible, recognizing the docs will serve new maintainers in the future

  • Develop a governance model

  • List who is involved and in what capacity

  • Think about a succession plan when the time comes for you to prioritize other things in life (which I believe is genuinely embodying the mentality of open source)

  • Share finances transparently

The major exception to this is when sensitive topics like Code of Conduct violations need to be handled privately.

N is for Nudges

Just as when someone transitions from an individual contributor to an engineering manager, when you shift from contributor to maintainer, your focus also shifts to people solutions instead of technical solutions. As a maintainer, you’re now responsible for leading discussions, planning the roadmap, onboarding new team members, and celebrating wins—among many other things.

However, unlike an engineering manager, you’ve dedicated yourself to an entire community instead of just one team, so understanding when it makes sense to delegate becomes even more vital.

As a maintainer, you may prefer the community side of things or not, so it’s essential to recognize your strengths in yourself and your fellow maintainers.

Either way, it’s more effective to empower others to contribute instead of contributing yourself all the time. 

Going from contributor to maintainer can be a tough transition, but shifting your mentality from “I can do this myself” to “Let me nudge this person to try this” can help. Nudging means “a light push,” and in open source, this can be a valuable way to transform someone from a passive contributor to a dedicated maintainer.

There will be many opportunities for you as a maintainer to nudge other maintainers in an empowering way which, in turn, will enable you to learn valuable leadership skills.

Below are some examples of how you can embody this value of positively nudging others as a maintainer in practice:

  • Recognize what skills fellow maintainers are interested in learning and index for that

  • Assign fellow maintainers tasks where you think there’s a growth opportunity and explain why

  • Nudge a fellow maintainer for feedback

  • Gauge the interest of repeat contributors in becoming a maintainer

  • Nudge a contributor to go in a different technical direction from a place of positive intent

W is for Warmth

Whether your project has 3 or 3,000 contributors, how you interact with them defines the project’s culture and how likely the community is to thrive. 

Warmth isn’t just about being positive in interactions and assuming the best intentions but also about creating an environment where contributors of all levels can thrive.

The easiest way to infer how warm a project is, is by seeing how those with the least amount of experience are treated, like first-time contributors to open source in general. It doesn’t matter how complicated your project is; there should be a path for someone knowledgeable but new to open source to understand how they can provide value.

Below are some examples of how you can embody this value of being warm and welcoming as a maintainer in practice:

  • Publish community health files (Code of Conduct, Contributing guide)

  • Take complaints seriously

  • Remove bad actors who are causing a negative experience for others

  • Provide resources or links to explain complex logic or jargon

  • Avoid language that comes across as demeaning or apathetic

  • Use the “Good First Issue” label to help new contributors find ways to pitch in

  • Identify ways for people to contribute that aren’t necessarily code-related (design, documentation, project planning, etc.)

  • Celebrate wins for all types of contributions, whether they're technical or non-technical

A is for Automation

Who doesn’t love a good bot? I love to use GitHub Actions, integrations, and other tools that make it easy to catch errors for every new PR created in the repos I maintain. 

For example, linters and style-checkers help ensure that code meets a project’s standards. First-time contributors appreciate this because they get immediate feedback and can feel more confident knowing all the checks are green as they get their PR ready for review. 

As maintainers, we also reap the benefits by feeling more confident approving a PR that has undergone a more thorough automated vetting process.

You can explore all the different GitHub Actions and apps through the Marketplace. You can also find many use cases for Actions through the awesome list.

Below are some examples of what you can configure to your project to make automation work to your advantage as a maintainer:

You can also take advantage of GitHub's baked-in settings or file types to further automate and streamline your repos:

R is for Recognition

It’s no secret that working as a maintainer can be pretty thankless. Thankfully (pun intended), you don’t have to be a part of that trend and can instead create clear paths to recognition amongst contributors and the wider maintainer team.

Naturally, you can get started with your contributing.md guide. But often and ironically enough, a missing piece in these guides is explicitly calling out the benefits of contributing. Out of the multitude of projects out there, why put in the time and energy for this one?

Whether the recognition is more abstract, like increased credibility with a specific technology (e.g., you’re contributing to a project that uses one of the popular static site generators in the world) or more tangible (e.g., a testimonial after 10 merged PRs), having clear pathways outlined can lead to an environment where contributing is a source of pride and satisfaction, not stress.

Below are some examples of how maintainers can be recognized after X number of contributions, the main ways being to provide visibility and credibility.

Visibility

Providing visibility can be a terrific low-lift way of providing much-earned recognition to maintainers. It also allows folks to instantly become passive project ambassadors and help spread the word. Here are some ways to provide visibility:

  • If your project is part of a GitHub organization, add maintainers to the organization so they can publicly display it on their profiles.

  • Create a custom project badge that maintainers can add to their profile READMEs

  • Showcase maintainers on the sponsors or funding page

  • Amplify maintainers on marketing channels (social media, blog, etc.)

  • Provide maintainers special privileges or badges in relevant community spaces

  • Create a project on LinkedIn/Polywork/etc. and add them as contributors

  • Highlight maintainers in the release note

Sometimes, your project may get enough recognition that folks are invited to speak about it at conferences or through a podcast. Remember to shout out to all the folks who supported you and center on “we,” not “I.”

For example, say: “this project wouldn’t have been possible without the help of all our amazing maintainers, and I’d like to give a special shout out to [maintainer's name] who recently helped us resolve this tough regression.”

Credibility

Even non-code contributors to a project can boost their credibility as engineers by showcasing the valuable skills they bring to a project. Some ways you can support those contributors include: 

  • Offer a testimonial about what it was like to work with them on the project. For example, you can give them a recommendation through LinkedIn.

  • Provide sample sentences that contributors can share on their website/LinkedIn under “Projects” for specific roles (engineering, design, technical docs). For example: “contributed to the design system of nonprofit ABC’s open-source website, which gets 10K monthly views and led to increased scalability and accessibility.”

Compensation

Providing compensation for open source contributions is much less common. Still, if your project is at a level with funding, you can create a bug bounty program or a straightforward process to becoming a paid maintainer. If you can’t send money, you can offer to send maintainers swag such as a shirt or stickers. Naturally, providing swag depends on whether or not you have the financial flexibility to do this, but it’s a fun conversation starter and can help spread the word. Plus, it just feels cool having custom swag.

D is for Dedication

Being a maintainer means being in a leadership position. While it may be different from what you might imagine traditional leaders have ownership over, the burden of being responsible and accountable to others is still there.

As a maintainer, you dedicate your time and energy to other people as much as you do to the code itself. But that doesn’t mean this project has to be the end-all, be-all for you. It’s also worth remembering that you never know when external factors, such as health or family emergencies, might make maintaining a project untenable. It’s critical to recognize your boundaries and plan for succession when other things in your life take higher priority. 

Leadership transitions often lead to a profound loss of historical knowledge, so planning ahead, even if you have no plans to step down as a maintainer, signifies a true sign of dedication to the project. You can ensure a more seamless and positive transfer of ownership to continue.

Below are examples of how to embody dedication to a project:

  • Support and empower fellow maintainers.

  • Be responsive on communication channels.

  • Take accountability when things go wrong.

  • Recognize your boundaries and share when you need time off.

  • Plan for succession and identify future maintainers.

Final thoughts

I hope maintainers can find a starting guide for their projects with this framework, as I believe that great maintainers can create future great maintainers.

How do you know you’ve made it as a maintainer? My day came when I found a blog post by a developer named Isabel Costa. She talked about her experience contributing to open source for the first time. And it was for contributing to one of my projects! Isabel is now shining bright as a GitHub star, and I’m grateful to have been part of her journey there.

I often wonder what would have happened if I had gotten a different response the first few times I decided to contribute to larger projects. Would I have had the motivation to keep going?

As a maintainer, you hold the power to make or break someone’s first-time experience in open source. As the saying goes: “With great power comes great responsibility.” Great maintainers create other great maintainers.

If we can create environments where maintainers feel valued and recognized, we can continue making OSS’s trajectory go onward and upward!

Hey! I’m Frances Coronel. I worked at Slack for four years on their customer acquisition team, and am currently engineer number three at the startup Byteboard. I live in Inglewood with my partner Nolan and my corgis, Luna and Sueño. In my free time, I like to train my dogs, do house renovations, blog, and contribute to open source projects.

About The
ReadME Project

Coding is usually seen as a solitary activity, but it’s actually the world’s largest community effort led by open source maintainers, contributors, and teams. These unsung heroes put in long hours to build software, fix issues, field questions, and manage communities.

The ReadME Project is part of GitHub’s ongoing effort to amplify the voices of the developer community. It’s an evolving space to engage with the community and explore the stories, challenges, technology, and culture that surround the world of open source.

Follow us:

Nominate a developer

Nominate inspiring developers and projects you think we should feature in The ReadME Project.

Support the community

Recognize developers working behind the scenes and help open source projects get the resources they need.