Project Governance: v1

[JoshuaKGoldberg]

Context

Hi everyone! The typescript-eslint project has grown a ton over the last few years. We've grown to five folks with commit access (@armano2, @bradzacher, @JamesHenry, @Josh-Cena, and myself); documentation has moved from .md files in GitHub to a full https://typescript-eslint.io site complete with contributing & maintenance docs; we're close to releasing the next v6 major version with tons of improvements. Lots of awesome growth & exciting upcoming stuff! 🚀

As part of supporting the project's growth, we'd like to get the "governance" processes (how we manage the project) documented in a clear way that's visible to the community. We see a few major benefits from doing so:

• We want it to be clear how & why we do the things we do (especially around compensation and expectations around roles)
• We want community input to make sure we're doing things the right way & focusing on truly useful improvements
• As we add to the processes over time, it'll be easier to make those changes clear & reviewable by everyone

So, to those ends, the following is a "v1" proposal of documenting our project governance. Its present state mostly formalizes how we act today, with small changes mostly made for clarity or for small improvements.

Our Ask Of You

Please read over the description & leave your feedback as threaded GitHub discussions here. We'd love to hear anything from you: what do you like? What don't you like? What should we know or think about that we aren't yet?

Please be kind - we've never done this before and recognize we might not know what impractical or terrible things we're doing. If there's anything sensitive you don't feel comfortable talking about in public, I'd encourage you to email one of the maintainers (I'm me [at] joshuakgoldberg [dot] com) and/or DM one of us on the typescript-eslint Discord server.

Timeline

Tentatively, we'll go with a July 14th deadline for public discussion here to allow one month of community input.

• April: Review this document privately
• May: Privately share with other open source maintainers in our network
• Mid-June: Post GitHub discussion, shared on Bsky & Discord & Mastodon & Twitter
• ~July: Formalize into the https://typescript-eslint.io/maintenance docs
• ~July: Add a typescript-eslint.io/team page to the docs

Edit: see #8020 for the last two stages.

We intend on following this up later in the year with updates to reflect improvements we want to make.
We'll also work on this continuously over time as the project grows and we learn more about governance.

Contribution Tiers

These tiers of contributors, committers, and maintainers roughly reflect how we've worked this past year.

Note that these are approximate numbers. We're a small enough team to informally discuss changes ad hoc and allow off-by-one-or-two months.

Tier	Entry Requirements	Monthly Expectations	Monthly Reimbursement
Contributor	1 point	(none)	(none)
Code Contributor	1 point in pull requests	(none)	(none)
Committer	~5 points in issues ~5 points in pull requests ~15 points total 2 of 4 consecutive active months	~10 points	1 share / active month
Maintainer	~10 points in issues ~10 points in pull requests ~30 points total 3 of 6 consecutive active months	~20 points	2 shares / active month

Each tier will be given a role on Discord.

All tier members can opt out of their tier -and therefore role- at will.
Tier members otherwise stay at their tier indefinitely.

The pool of reimbursement money is sourced from all project sponsorship -mostly Open Collective and Tidelift-, then distributed monthly to eligible contributors.

Rough Pointing

Although it's impossible to accurately estimate software projects, we want to roughly establish expectations of effort+time spent on the tiers. These are all rough estimations and should be taken as approximate starting guides to consider.

We treat both the creation and review of issues and PRs along the rough scale of:

Size	Description	Points	Examples
Trivial	Small typos or single-file bugfixes	1	#6976, #6992
Straightforward	2-3 files at most, with minimal logical changes	2	#6780, #6910
Large	Multi-file logical changes that require real review+thought	3	#6107, #6907
Unusual	Dozen+ file logical changes that require deep investigation	≥5*	#6084, #6777

*Unusually large efforts may be >5 points at maintainer discretion depending on time spent.

Any other activities (e.g. responding to Discord threads, working on upstream dependencies, …) should be treated as gaining points equal to their nearest equivalent point task.

Tier Advancement

When a contributor or committer seems to roughly qualify for a next tier, members of later tiers will set up a private discussion and poll to advance them to that tier. This is mostly to prevent system gaming (e.g. an otherwise-inactive contributor sending a dozen 1-point docs fixes).

Maintenance Tasks

Issue Triage

At reviewer discretion, straightforward issues may be marked as approved by any committer or maintainer. This includes docs enhancements, bug fixes, and feature additions.

Non-straightforward issues may be marked as approved with either two committer approvals or one maintainer approval. These include significant internal refactors and non-breaking public API changes.

“Unusual”-categorized issues require a public discussion followed by two maintainer approvals. These include significant refactors with cross-project and public API ramifications.

Pull Request Reviews

At reviewer discretion, straightforward pull requests may be merged with a single approval by any committer or maintainer. This includes docs enhancements, bug fixes, and feature additions.

Non-straightforward pull requests may be merged with either two committer approvals or one maintainer approval. These include multi-package internal refactors and non-breaking public API changes.

“Unusual”-categorized pull requests require two maintainer approvals. These include significant refactors with cross-project and public API ramifications.

Monthly Reimbursements

Team members will be reimbursed the minimum of their activity level and their tier. Each month:

• Committers and maintainers who hit their expectation receive their full shares
• Committers and maintainers who hit roughly half their expectation receive half shares

Community Reimbursements

Contributors who contribute nontrivial changes in a month (roughly ≥5 points and at least one large item) may be privately nominated at any time by a committer or maintainer to be reimbursed at the equivalent shares.

Our intention is to always do this for contributors who submit Large or greater contributions and don't need significant assistance in getting them merged.

Changes to Governance

Any changes to this document will be posted for open discussion on GitHub Discussions, and kept open for at least one month. The discussion will be shared at the beginning, middle, and end of that month on Discord and all our social media accounts.

Out of Scope

Likely Soon

These points we will likely look into after this governance proposal has settled. They will be largely informed by how the first few months of governance go.

• Automation: collecting detectable contributions automatically to generate starting suggestions for maintenance and reimbursements. We're interested in this to save ourselves time, with the caveat that this will always need manual oversight and review.
• Community contributions: we may eventually add explicit metrics for helping users via blogs, Discord, and other platforms. For now we're focusing on core repository maintenance.
• Dependency sponsorships: we'd like to eventually set aside a portion of our sponsorship to go to sub-dependencies. This is a complex, nuanced topic and will come later.

Longer Term

We very much want to tackle these points, but they're not immediately next in line.

• Apprenticeship/fellowship/internship program: we'd love to set aside money & time to explicitly train novice community members, such as through programs like Google Summer of Code or Outreachy. This will take more thought to do well, so we'll figure out the smaller Likely Soon items first.

Not Likely Soon

These points we're explicitly staying away from for the forseeable future. We may eventually need them some years from now if we significantly scale up in size.

• Time requirements to stay as a committer or maintainer: we don't wish to penalize anybody for taking multiple months away.
• Technical Steering Committee (”TSC”): for now, informal discussions over Discord and GitHub have sufficed.
• Working Groups: for now, catch-all committers and maintainers have sufficed.

Thanks

Appreciation to the following community members for providing input:

• Alex Katt
• Chrissy Codes
• Dan Vanderkam
• Shauna Gordon-McKeon
• Suzuki Sosuke

(Did we miss your name? That was a mistake - please let us know!)

General Resources

• Governing Open
• Open Source Guides

(Know of other existing governance resources we should look at? Please let us know!)

Prior Art

These existing governance docs in particular were helpful to us in making this proposal:

• Astro: github.com/withastro/.github/blob/main/GOVERNANCE.md
• ESLint: eslint.org/docs/latest/contribute/governance
• MDN: developer.mozilla.org/en-US/docs/MDN/Community/Roles_teams
• Node.js: github.com/nodejs/node/blob/main/GOVERNANCE.md

(Know of other existing governance docs we should look at? Please let us know!)

[JoshuaKGoldberg]

Following up: we can consider this process ratified. Thanks everyone!

Later this year, look forward to the touchups (i.e. Discord roles and user payments) rolling out. 🎉