typescript-eslint · JoshuaKGoldberg · Dec 24, 2023 · Nov 29, 2023 · Dec 12, 2023 · Dec 12, 2023
diff --git a/docs/Maintenance.mdx b/docs/Maintenance.mdx
@@ -12,3 +12,32 @@ We keep it in the open for visibility into our processes.
 If you're reading this as a new maintainer: welcome!
 We're happy to have you! ❤️‍🔥
 :::
+
+## Governance
+
+We follow a loose governance model that covers roles on the maintenance team and their associated responsibilities.
+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
+
+The following pages are a rough "v1.x" of our governance.
+We do our best to roughly adhere to this model - though at times we may shortcut tasks if there is no downside in doing so.
+
+### Changes to Governance
+
+Any changes to this document will be posted for open discussion on the [typescript-eslint GitHub Discussions](https://github.com/typescript-eslint/typescript-eslint/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.
+
+## Providing Feedback
+
+We're always receptive to suggestions on how to improve our processes!
+For general feedback, we'd suggest posting in the [`#development` channel on Discord](https://discord.com/channels/1026804805894672454/1088474511759917106).
+We can help you turn that into a GitHub discussion.
+
+:::note
+Please be kind: open source governance is an unsolved challenge.
+We might not know what impractical or non-ideal things we're doing.
+If there's anything sensitive you don't feel comfortable talking about in public, you can always DM or email one of the maintainers privately.
+:::
diff --git a/docs/maintenance/Contributor_Tiers.mdx b/docs/maintenance/Contributor_Tiers.mdx
@@ -0,0 +1,177 @@
+---
+id: contributor-tiers
+title: Contributor Tiers
+---
+
+These tiers of contributors, committers, and maintainers roughly reflect how we've worked the past several years.
+
+<table>
+  <thead>
+    <tr>
+      <th>Tier</th>
+      <th>Entry Requirements</th>
+      <th>Monthly Expectations</th>
+      <th>Monthly Reimbursement</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <th>Contributor</th>
+      <td>1 point</td>
+      <td>
+        <em>(none)</em>
+      </td>
+      <td>
+        <em>(none)</em>
+      </td>
+    </tr>
+    <tr>
+      <th>Code Contributor</th>
+      <td>1 point in pull requests</td>
+      <td>
+        <em>(none)</em>
+      </td>
+      <td>
+        <em>(none)</em>
+      </td>
+    </tr>
+    <tr>
+      <th>Committer</th>
+      <td>
+        ~5 points in issues
+        <br />
+        ~5 points in pull requests
+        <br />
+        ~15 points total
+        <br />2 of 4 consecutive active months
+      </td>
+      <td>~10 points</td>
+      <td>~1 share / active month</td>
+    </tr>
+    <tr>
+      <th>Maintainer</th>
+      <td>
+        ~10 points in issues
+        <br />
+        ~10 points in pull requests
+        <br />
+        ~30 points total
+        <br />3 of 6 active months
+      </td>
+      <td>~20 points</td>
+      <td>~2 shares / active month</td>
+    </tr>
+  </tbody>
+</table>
+
+:::note
+We treat everything here as approximate numbers.
+We're a small enough team to informally discuss changes ad hoc and allow off-by-one-or-two months.
+:::
+
+## 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:
+
+<table>
+  <thead>
+    <tr>
+      <th>Size</th>
+      <th>Description</th>
+      <th>Points</th>
+      <th>Examples</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <th>Trivial</th>
+      <td>Small typos or single-file bugfixes</td>
+      <td>1</td>
+      <td>
+        <a href="https://github.com/typescript-eslint/typescript-eslint/pull/6976">
+          #6976
+        </a>
+        , <a href="https://github.com/typescript-eslint/typescript-eslint/issues/6992">#6992</a>
+      </td>
+    </tr>
+    <tr>
+      <th>Straightforward</th>
+      <td>2-3 files at most, with minimal logical changes</td>
+      <td>2</td>
+      <td>
+        <a href="https://github.com/typescript-eslint/typescript-eslint/pull/6780">
+          #6780
+        </a>
+        , <a href="https://github.com/typescript-eslint/typescript-eslint/pull/6910">#6910</a>
+      </td>
+    </tr>
+    <tr>
+      <th>Large</th>
+      <td>Multi-file logical changes that require real review+thought</td>
+      <td>3</td>
+      <td>
+        <a href="https://github.com/typescript-eslint/typescript-eslint/pull/6107">
+          #6107
+        </a>
+        , <a href="https://github.com/typescript-eslint/typescript-eslint/pull/6907">#6907</a>
+      </td>
+    </tr>
+    <tr>
+      <th>Unusual</th>
+      <td>Dozen+ file logical changes that require deep investigation</td>
+      <td>≥5*</td>
+      <td>
+        <a href="https://github.com/typescript-eslint/typescript-eslint/pull/6084">
+          #6084
+        </a>
+        , <a href="https://github.com/typescript-eslint/typescript-eslint/pull/6777">#6777</a>
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+> \*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 in terms of complexity and effort.
+
+## Advancement
+
+Each tier corresponds to a role on Discord and GitHub.
+When you first hit a tier, you can post in the [`#roles` channel on Discord](https://discord.com/channels/1026804805894672454/1184219870691328051).
+
+We will confirm privately that you've hit the intent of the contribution tiers.
+We'll then grant you the role on Discord and GitHub and profusely thank you for everything you've done. ❤️
+
+### Recognition
+
+Depending on the tier you reach, you can also provide information for an upcoming _Team_ page:
+
+- Contributor and Code Contributor: Preferred photo, name, social media handles
+- Committer and Maintainer: ~2 paragraph bio of yourself
+
+See existing bios for examples of what to put.
+
+:::note
+You can decline to opt into the Discord role or site recognition, and you can always opt out after the fact.
+Nothing is mandatory.
+We just like including recognition as thanks for working with us. 💕
+:::
+
+## Reimbursement
+
+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
+
+Reimbursements are generally handled through [our Open Collective page](https://opencollective.com/typescript-eslint).
+
+### 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.
diff --git a/docs/maintenance/Governance.mdx b/docs/maintenance/Governance.mdx
@@ -0,0 +1,4 @@
+---
+id: governance
+title: Governance
+---
diff --git a/docs/maintenance/Issues.mdx b/docs/maintenance/Issues.mdx
@@ -5,14 +5,25 @@ title: Issues
 
 This document serves as a guide for how you might manage our [GitHub Issues](https://docs.github.com/issues), also known as issue triaging.
 
-Use your best judgement when triaging issues, and most of all remember to be **kind, friendly, and encouraging** when responding to users.
+Use your best judgement when triaging issues, and most of all remember to be **encouraging, friendly, and kind** when responding to users.
 Many users are new to open source and/or typed linting.
 It's imperative we give them a positive, uplifting experience.
 
 :::tip
 If you're ever unsure on any part of issue management, don't hesitate to loop in a maintainer that has more context to help!
 :::
 
+## Governance
+
+Per the scales from [Contribution Tiers > Pointing](./Contributor_Tiers.mdx#pointing):
+
+- Straightforward: at reviewer discretion, may be marked as approved by any committer or maintainer.
+  This includes docs enhancements, bug fixes, and feature additions.
+- Non-straightforward: 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: require a public discussion followed by two maintainer approvals.
+  These include significant refactors with cross-project and public API ramifications.
+
 ## Issue Flow
 
 :::note
@@ -21,17 +32,17 @@ Don't treat these as exact responses you must use: they're just a starting copy+
 Please do adopt your specific responses to your personal tone and to match the thread for non-straightforward issues.
 :::
 
-[Issues pending triage](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aopen+is%3Aissue+label%3Atriage) are searchable the `triage` label.
+[Issues pending triage](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aopen+is%3Aissue+label%3Atriage) are searchable with the `triage` label.
 That label is added automatically when a new issue is created.
 Most issues go through the following review flow when created or updated:
 
 1. A maintainer ensures the issue is valid:
    - If the poster didn't fill out an appropriate template with enough information:
-     - Add the `please fill out the template` and `awaiting response` labels
+     - Add the `please fill out the template` and `awaiting response` labels, and remove the `triage` label
      - Ask the poster for more information using a _Needs More Info_ response
    - If it's a duplicate of an issue that already exists:
-     - Add the `duplicate` label and remove the `bug` label
-     - If it's an obvious duplicate, post a _Clearly Duplicate Issue_ response
+     - Add the `duplicate` label and remove the `triage` label
+     - If it's an obvious duplicate, post a _Clearly Duplicate Issue_ response linking to the existing issue
      - If it's not an obvious duplicate, link to the existing issue and explain why
    - If the code is working as intended:
      - Add the `working as intended` label and remove the `bug` and `triage` labels
@@ -135,6 +146,6 @@ Every so often, we like to [search for open issues `awaiting response`](https://
 Our flow for issues that have been waiting for >=1 month is:
 
 1. Ping the author with a message like the _Checking In_ template
-2. Add the `stale` label to the issue
-3. Wait 2 weeks
-4. If they still haven't responded, close the issue with a message like the _Pruning Stale Issue_ template
+1. Add the `stale` label to the issue
+1. Wait 2 weeks
+1. If they still haven't responded, close the issue with a message like the _Pruning Stale Issue_ template
diff --git a/docs/maintenance/Pull_Requests.mdx b/docs/maintenance/Pull_Requests.mdx
@@ -13,6 +13,17 @@ It's imperative we give them a positive, uplifting experience.
 If you're ever unsure on any part of PR reviews, don't hesitate to loop in a maintainer that has more context to help!
 :::
 
+## Governance
+
+Per the scales from [Contribution Tiers > Pointing](./Contributor_Tiers.mdx#pointing):
+
+- Straightforward: At reviewer discretion, may be merged with a single approval by any committer or maintainer.
+  This includes docs enhancements, bug fixes, and feature additions.
+- Non-straightforward: 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: require two maintainer approvals.
+  These include significant refactors with cross-project and public API ramifications.
+
 ## PR Flow
 
 :::note

diff --git a/docs/maintenance/Major_Release_Steps.mdx → docs/maintenance/Releases.mdx b/docs/maintenance/Major_Release_Steps.mdx → docs/maintenance/Releases.mdx
@@ -1,9 +1,18 @@
 ---
-id: major-release-steps
-title: Major Release Steps
+id: releases
+title: Releases
 ---
 
-## 1. Pre-Release Preparation
+[Users > Releases](../users/Releases.mdx) describes how our automatic releases are done.
+There is generally no maintenance activity we need to take for the weekly releases.
+
+However, there are two kinds of releases we infrequently go through that each require manual effort.
+
+## Major Releases
+
+Per [Users > Releases > Major Releases](../users/Releases.mdx#major-releases), we infrequently release major versions with accumulated breaking changes.
+
+### 1. Pre-Release Preparation
 
 1. Create a milestone by the name of the release [example: [Milestone 6.0.0](https://github.com/typescript-eslint/typescript-eslint/milestone/8)].
 1. If an issue for changes to recommended rule configs doesn't yet exist, create one [example: [Changes to the `recommended` sets for 5.0.0](https://github.com/typescript-eslint/typescript-eslint/issues/5900)].
@@ -18,7 +27,7 @@ title: Major Release Steps
      - Its publish command should be `npx lerna publish premajor --loglevel=verbose --canary --exact --force-publish --yes --dist-tag rc-v${major}`.
    - Merge this into `main` once reviewed and rebase the `v${major}` branch.
 
-## 2. Merging Breaking Changes
+### 2. Merging Breaking Changes
 
 1. Send a PR from `v${major}` to `main` [example: [v6.0.0](https://github.com/typescript-eslint/typescript-eslint/pull/5886)].
 1. Change all [breaking change PRs](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aissue+is%3Aopen+label%3A%22breaking+change%22) to target the `v${major}` branch.
@@ -34,11 +43,21 @@ _Non_-breaking changes can be merged to `main` or the major branch.
 They don't need any special treatment.
 :::
 
-## 3. Releasing the Version
+### 3. Releasing the Version
 
-1. Discuss with the maintainers to be ready for an [out-of-band](#out-of-band) release. Doing this manually helps ensure someone is on-hand to action any issues that might arise from the major release.
+1. Discuss with the maintainers to be ready for an [out-of-band](#out-of-band-releases) release. Doing this manually helps ensure someone is on-hand to action any issues that might arise from the major release.
 1. Prepare the release notes. Lerna will automatically generate the release notes on GitHub, however this will be disorganized and unhelpful for users. We need to reorganize the release notes so that breaking changes are placed at the top to make them most visible. If any migrations are required, we must list the steps to make it easy for users.
+   - Example release notes: [`v5.0.0`](https://github.com/typescript-eslint/typescript-eslint/releases/tag/v5.0.0), [`v4.0.0`](https://github.com/typescript-eslint/typescript-eslint/releases/tag/v4.0.0), [`v3.0.0`](https://github.com/typescript-eslint/typescript-eslint/releases/tag/v3.0.0)
+1. Finally, tweet the release on the `@tseslint` twitter with a link to the GitHub release. Make sure you include additional information about the highlights of the release!
 
-- Example release notes: [`v5.0.0`](https://github.com/typescript-eslint/typescript-eslint/releases/tag/v5.0.0), [`v4.0.0`](https://github.com/typescript-eslint/typescript-eslint/releases/tag/v4.0.0), [`v3.0.0`](https://github.com/typescript-eslint/typescript-eslint/releases/tag/v3.0.0)
+## Out-of-Band Releases
 
-1. Finally, tweet the release on the `@tseslint` twitter with a link to the GitHub release. Make sure you include additional information about the highlights of the release!
+Per [Users > Releases > Out-of-Band Releases](../users/Releases.mdx#out-of-band-releases), we may manually trigger a new release for a rare emergency such as a critical regression.
+If that happens:
+
+1. Mention in any relevant issue(s) that you intend to release an out-of-band release
+1. Post in a private maintenance Discord channel that you're working on it
+1. Send a pull request resolving the issue(s)
+1. Waiting up to a day (as reasonable) for approval before merging the PR
+1. Trigger the private release workflow to cause a new release
+1. Post back in those same issue(s) with a link to the newly released version(s)
diff --git a/...intenance/Dependency_Version_Upgrades.mdx → ...-requests/Dependency_Version_Upgrades.mdx b/...intenance/Dependency_Version_Upgrades.mdx → ...-requests/Dependency_Version_Upgrades.mdx
@@ -31,7 +31,7 @@ Whenever you discover any new areas of work that are blocked by dropping an old
 1. Upgrade the root `package.json` `devDependency` to the latest ESLint
 1. Add the new major version to the explicit `peerDependency` versions
 1. Check [`eslint-visitor-keys`](https://www.npmjs.com/package/eslint-visitor-keys) for a new version to be upgraded to as well.
-1. Update [Users > Dependency Versions > ESLint](../users/Dependency_Versions.mdx#eslint)
+1. Update [Users > Dependency Versions > ESLint](../../users/Dependency_Versions.mdx#eslint)
 
 ### Removing Support for an Old ESLint Version
 
@@ -42,7 +42,7 @@ Whenever you discover any new areas of work that are blocked by dropping an old
      - `/eslint.*5/i`
      - `/todo.*eslint.*5/i`
      - `/todo.*eslint/i`
-1. Update [Users > Dependency Versions > ESLint](../users/Dependency_Versions.mdx#eslint)
+1. Update [Users > Dependency Versions > ESLint](../../users/Dependency_Versions.mdx#eslint)
 
 See [chore: drop support for ESLint v6](https://github.com/typescript-eslint/typescript-eslint/pull/5972) for reference.
 
@@ -115,7 +115,7 @@ A single PR can remove support for old TypeScript versions as a breaking change:
 1. Update the root `package.json` `devDependency`
 1. Update the `SUPPORTED_TYPESCRIPT_VERSIONS` constant in `warnAboutTSVersion.ts`
 1. Update the `versions` constant in `version-check.ts`
-1. Update [Users > Dependency Versions > TypeScript](../users/Dependency_Versions.mdx#typescript)
+1. Update [Users > Dependency Versions > TypeScript](../../users/Dependency_Versions.mdx#typescript)
 1. Search for source code comments (excluding `CHANGELOG.md` files) that mention a now-unsupported version of TypeScript.
    - For example, to remove support for v4.3, searches might include:
      - `4.3`

diff --git a/docs/users/Dependency_Versions.mdx b/docs/users/Dependency_Versions.mdx
@@ -55,4 +55,4 @@ See: [Packages > Parser > `warnOnUnsupportedTypeScriptVersion`](../packages/Pars
 
 ## Dependant Version Upgrades
 
-See [Maintenance > Dependent Version Upgrades](../maintenance/Dependency_Version_Upgrades.mdx) for maintenance steps to update these versions.
+See [Maintenance > Dependent Version Upgrades](../maintenance/pull-requests/Dependency_Version_Upgrades.mdx) for maintenance steps to update these versions.
diff --git a/docs/users/Releases.mdx b/docs/users/Releases.mdx
@@ -73,9 +73,9 @@ We currently do not have a set schedule around when major releases shall be perf
 We keep a backlog of breaking issues as a milestone on GitHub that is named in the form `${major}.0.0`.
 When we do do a major release, we release a release candidate version to the `rc-v${major}` tag on npm for each commit to the major branch.
 
-See [Maintenance > Major Release Steps](../maintenance/Major_Release_Steps.mdx) for steps to perform a major release.
+See [Maintenance > Releases](../maintenance/Releases.mdx#major-releases) for steps to perform a major release.
 
-## Out-of-Band
+## Out-of-Band Releases
 
 We will do releases "out-of-band" (outside the [latest](#latest) schedule) for rare emergencies.
 We assess need on a case-by-case basis though generally an emergency is defined as a critical regression specifically introduced in the latest release.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -55,4 +55,4 @@ See: [Packages > Parser > `warnOnUnsupportedTypeScriptVersion`](../packages/Pars

		## Dependant Version Upgrades

		See [Maintenance > Dependent Version Upgrades](../maintenance/Dependency_Version_Upgrades.mdx) for maintenance steps to update these versions.
		See [Maintenance > Dependent Version Upgrades](../maintenance/pull-requests/Dependency_Version_Upgrades.mdx) for maintenance steps to update these versions.