Skip to content
swyx | @swyx

Artwork: Susan Haejin Lee

Breaking apart the monolith

The open source movement should really be modeled after social clubs and city governments.

Photo of swyx | @swyx

swyx | @swyx // Developer Advocate

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

Why must maintainers be “full stack”?

In software engineering, it is completely normal to specialize, whether working on product, platform, infrastructure, creative coding, or data science. 

But when it comes to open source, we expect maintainers to be consummate generalists: documentation, community, design, marketing, project management, support... oh, and code. And we expect them to deliver this full-stack maintainership for life.

For independent open source to be sustainable and accessible to all, we must explore ways of breaking apart the “maintainer monolith.” Fortunately, we don’t have to invent our solutions from scratch—we can look to centuries-old models of servant leadership from the government and social sectors for inspiration.

The solution may start with a simple file we’ll call MAINTAINERS.md.

Note: For the purposes of this article we focus on independent open source, as separate from commercial open source, which has its own, different, issues.

The social contract: Money doesn’t solve burnout

Many efforts to “fix” open source have been focused on the financial elements, while the human side has received a lot of sympathy but not a lot of solutions. The three main support models for independent open source that have emerged are corporate/personal sponsorship, paid support/training, and issue bounties. All are well intentioned and necessary, but together remain insufficient. In the JS ecosystem, Babel’s funding struggles have presaged open source developers turning to venture capital, or just diverting their efforts to closed source.

Money is, of course, very helpful toward long-term sustainability and funding dedicated, high-quality maintenance. But:

  • Discretionary funding is biased toward high visibility projects over critical, “boring” infrastructure, exacerbating the natural inequality by putting a dollar amount on it.

  • Automated funding is biased toward older projects (that aren’t necessarily actively maintained and may not need the money) and susceptible to ecosystem manipulation (people can break up code with the effect of goosing total numbers).

  • Allocation of funds in a collaborative project is difficult, as contribution isn’t adequately captured by the number of commits or lines of code or issues triaged.

  • Even the well-funded projects have budgets far below what the maintainers could get in a normal software job anyway.

  • Realistically only a very small percentage of projects ever attract a meaningful amount of funding, so the majority of open source needs non-financial solutions.

No matter how you slice it, the conclusion is clear: There will always be some amount of financial sacrifice in choosing to work on open source, and solutions that only address financial over human elements may make things worse by ratcheting up expectations for maintainers.

The motivations for the vast majority of maintainers will likely always be more personal than financial. This is a feature, not a bug: a movement predicated on giving away intellectual property encounters many conflicts if we insist that the only way for it to be sustainable is to capture more value. And yet, despite genuine desire for industry impact and personal satisfaction, generation after generation of maintainers starts strong and burns out just as quickly. Some attrition is to be expected—interests and priorities shift as life goes on—but we probably lose more than our fair share of maintainer talent because of our inadequate social, not financial, contracts.

Amidst a spate of recent, high-profile burnouts in the community, there’s been an increasing interest in the social contract of open source.

These are some actual quotes from maintainers:

  • “Sorry everybody, I failed... In order to develop [Docz], I need to wake up every day 3 hours earlier and go to bed 3 hours later.” - Pedro Nauck

  • “I do not wish to come off as anything but welcoming, however, I’ve made the decision to keep this project closed to contributions for my own mental health and long term viability of the project.” - Ben Johnson

  • “Running a successful open source project is just Good Will Hunting in reverse, where you start out as a respected genius and end up being a janitor who gets into fights.” - Chris Aniszczyk

  • “For years, I work on open-source projects but that sometimes means to be exposed. I am no longer strong enough for receiving free insults or sometime threats like it was in 2019.” - Thomas Schneider

  • “Maybe we can find a future for package indexes where maintainers of packages are not burdened further because the internet started depending on it. It’s not the fault of the creator that their creation became popular.” - Armin Ronacher

Does this sound like a healthy social contract to you?

Many efforts focus on chastising the unreasonably demanding open source user. Brett Cannon, member of the Python Steering Council, recently wrote about the philosophical divide between the literal legal open source contract (where software is provided for free, “as is”) and its mismatched social equivalent (where users treat maintainers as a means to an end instead of viewing every commit as a gift). Jan Lehnardt says the only way to cope is to stop caring.

Nadia Eghbal’s books Working in Public and Roads and Bridges dive deeper into the complex relationships between maintainers and their contributors, users, collaborators, and platforms. Open source has diversified from the Stallman-era “communitarian kibbutz” model into what she terms federations, clubs, stadiums, and toys. A clear understanding of what model a given project operates in can help to fine-tune the expectations of participation around it:

Inline1_Guide_Swyx

But perhaps not enough attention has been paid toward reframing the us-vs-them mentality dividing maintainers and everyone else. What if it were a norm for people to smoothly step up and down into service? Maintainership would not become an indefinite, unscoped, unlimited burden.

Look outside tech

I'm inspired by social clubs and city governments and believe people are driven by much more than money. They desire social status, power, impact, legacy, community, service, freedom, and a myriad of other motivations. The open source movement is only 20-something years old, but there are far more time-tested forms of public service and communal governance ideas that can invoke these:

  • Elections and fixed terms. Local government has its flaws, but by and large it seems to work for many towns and cities. Members of a community see issues that they wish to fix, and run for elections to gain the mandate to fix them. Those that don’t win the election aren’t locked out forever; they can wait for the next term and campaign again. In open source, this could mean project governance becomes more participatory, an alternative to the status quo where a project founder becomes the Benevolent Dictator For Life by default.

  • Real budgets with public accountability. Some amount of prestige does flow from having central financial authority. Social clubs have dues, governments collect taxes, and foundations have memberships. What if voting was tied to some form of financial contribution? This is less about “fixing open source” by financial means as discussed above, but more about raising the stakes and endowing the maintainer position with more than informal power. Public accountability, such as audited accounts and open meetings, would also be essential for meaningful budgets.

  • Separate responsibilities. Nobody in government or society is “full stack.” There is a president, a vice president, a treasurer, a social chair, and so on. This limits the expectations of each role and also helps provide some career progression should the person aspire toward more involved service. It also addresses the loneliness problem that many maintainers report having.

Everything I have discussed so far takes the form of centralized power, but I would be remiss not to acknowledge that Decentralized Autonomous Organizations have arisen to provide a distributed, and necessarily open source, alternative. However these are younger and much less proven, and until such time that DAOs can write code, I think they can be ignored.

I am not an expert in government studies and social service, so I hope others will point out better models to study or well-known pitfalls to avoid. But I feel confident that those of us in tech, trying to figure out these very human problems, can have something to learn by borrowing ideas from these time-tested models from outside tech.

What a MAINTAINERS.md could look like

Every open source project has a file listing their code dependencies, like package.json or Gemfile or go.mod. The movement toward documenting for human dependencies has been relatively slower on the uptick:

  • CONTRIBUTING.md is the earliest (2012) form of human-file, but focuses on documenting internal code style and collaboration instructions, rather than acknowledging present contributors.

  • CODEOWNERS.md is a 2017 addition to GitHub, documenting who owns which parts of a codebase (and therefore needs to sign off on code reviews impacting those).

  • Last year, ARCHITECTURE.md gained some adoption by introducing project architecture, embraced in projects like rust-analyzer, esbuild, and Caddy.

All of these make the open source project more welcoming to new contributors, but are still very focused on code as the primary unit of contribution. In 2016, Kent C. Dodds expanded this scope dramatically by introducing All Contributors, which recognizes no less than 33 different types of contributions that people can make to an open source project. However, because contribution is binary and permanent, it can get difficult to manage a long list of drive-by contributions and doesn’t specifically incentivize people to step up as core maintainers.

Inline 2_Guide_Swyx

In 2019, GitHub made a big step towards separating out maintainer concerns by adding triage and maintain roles: “If a contributor proves their ability to drive technical discussions or lead development of your project, you can empower them to take on additional issue or repository management responsibilities without needing to also grant the ability to modify your project’s source code or change potentially destructive repository settings.”

This move is mostly based on security and trust level, and did not get much fanfare as it is just another collaborator permission setting inside GitHub. However, I believe it was a critical step forward to splitting up the maintainer monolith. I think this idea needs to develop beyond a small platform feature into a prominent element of open source with cultural significance.

Here’s what a minimal MAINTAINERS.md could potentially include:

Maintainers Team Jun 2021 - May 2023 - Tech Lead: - Documentarian: - Issue/PR Triage: Jun 2019 - May 2021 - Tech Lead: - Documentarian: - Issue/PR Triage:

Other roles that can be added as needed:

  • Community Builder

  • Project Manager

  • User Researcher

  • Quality Assurance

  • Feature Owner

  • Event Planner

  • Marketing/Developer Relations

  • Designer

  • Treasurer

  • Intern

I highlighted the first three roles because those are the most central: the reality is that most projects do not have a massive volunteer crew to recruit for these roles. MAINTAINERS.md needs to scale together with project size. The other important element of this design is the limited term, which makes it clear that others can step up if they wish, and that the commitment isn’t for life.

Although MAINTAINERS.md would primarily be a cultural movement, GitHub and other code hosting platforms can play a huge role in recognizing these forms of specialized maintainership, from pride of placement in the project sidebar, to special badges that recognize maintainers together with the cohort they served on. 

Y Combinator founders are famous for identifying by the cohort they were in as a shibboleth: “I was in YC W18” indicates immediate club membership to another YC founder. Why can’t we create an equivalent career milestone for open source service?

At Airbyte, where we have hundreds of open source connectors for every kind of data source imaginable, we are experimenting with this separation of concerns by creating an official community maintainer program that provides both special status and monetary rewards for PR and issue triage without needing to assume “full stack” responsibility. This is the first of many steps towards a new participative model that we hope will blaze the path for the growing group of venture-backed developer tools companies with significant community value add.

More extreme options are also on the table: for example, if nobody steps up to maintain a project, it might automatically get archived. Risk of loss, even though reversible, has proven to be a key motivator for projects like Storybook and youtube-dl where the community has stepped in to resuscitate a project.

Taking the next step

MAINTAINERS.md is the first step towards finding human solutions to human problems: how do you incentivize collaboration and public service at a level far beyond what you can ever pay for? Solving this requires a fuller understanding of human motivations, but here’s the good news: Humanity has been working on solutions for this since before computers existed. Computer science, meet social science.

Hey, I'm swyx! I help build great developer experiences, from documentation to dev advocacy to dev communities, and I currently serve as head of developer experience at Airbyte.io, the ELT data integration tool with the largest community of open source connectors. I've started and run communities for hundreds of thousands of developers, like Svelte Society, /r/reactjs, and the React TypeScript Cheatsheet. I am a GitHub Star and frequent writer and speaker best known for the Learn in Public movement. I also wrote The Coding Career Handbook with more advice for engineers going from Junior to Senior!

More stories

Functional Programming 101

Cassidy Williams // Remote

Continuously deploying custom storefronts

Steve Martinelli & Genevieve L'Esperance // Shopify

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.