Skip to content

Commit fe8e844

Browse files
JoshuaKGoldbergauvred
JoshuaKGoldberg
authored and
auvred
committed
docs: formalized v1 maintenance docs (typescript-eslint#8020)
* docs: formalized v1 maintenance docs * Remove /team placeholder page and components * Finished TODOs * proofreading * Don't remove 'bug'
1 parent 0f74914 commit fe8e844

File tree

10 files changed

+289
-27
lines changed

10 files changed

+289
-27
lines changed

‎docs/Maintenance.mdx

+29
Original file line numberDiff line numberDiff line change
@@ -12,3 +12,32 @@ We keep it in the open for visibility into our processes.
1212
If you're reading this as a new maintainer: welcome!
1313
We're happy to have you! ❤️‍🔥
1414
:::
15+
16+
## Governance
17+
18+
We follow a loose governance model that covers roles on the maintenance team and their associated responsibilities.
19+
We see a few major benefits from doing so:
20+
21+
- We want it to be clear how & why we do the things we do _(especially around compensation and expectations around roles)_
22+
- We want community input to make sure we're doing things the right way & focusing on truly useful improvements
23+
- As we add to the processes over time, it'll be easier to make those changes clear & reviewable by everyone
24+
25+
The following pages are a rough "v1.x" of our governance.
26+
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.
27+
28+
### Changes to Governance
29+
30+
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.
31+
The discussion will be shared at the beginning, middle, and end of that month on Discord and all our social media accounts.
32+
33+
## Providing Feedback
34+
35+
We're always receptive to suggestions on how to improve our processes!
36+
For general feedback, we'd suggest posting in the [`#development` channel on Discord](https://discord.com/channels/1026804805894672454/1088474511759917106).
37+
We can help you turn that into a GitHub discussion.
38+
39+
:::note
40+
Please be kind: open source governance is an unsolved challenge.
41+
We might not know what impractical or non-ideal things we're doing.
42+
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.
43+
:::

‎docs/maintenance/Contributor_Tiers.mdx

+177
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
---
2+
id: contributor-tiers
3+
title: Contributor Tiers
4+
---
5+
6+
These tiers of contributors, committers, and maintainers roughly reflect how we've worked the past several years.
7+
8+
<table>
9+
<thead>
10+
<tr>
11+
<th>Tier</th>
12+
<th>Entry Requirements</th>
13+
<th>Monthly Expectations</th>
14+
<th>Monthly Reimbursement</th>
15+
</tr>
16+
</thead>
17+
<tbody>
18+
<tr>
19+
<th>Contributor</th>
20+
<td>1 point</td>
21+
<td>
22+
<em>(none)</em>
23+
</td>
24+
<td>
25+
<em>(none)</em>
26+
</td>
27+
</tr>
28+
<tr>
29+
<th>Code Contributor</th>
30+
<td>1 point in pull requests</td>
31+
<td>
32+
<em>(none)</em>
33+
</td>
34+
<td>
35+
<em>(none)</em>
36+
</td>
37+
</tr>
38+
<tr>
39+
<th>Committer</th>
40+
<td>
41+
~5 points in issues
42+
<br />
43+
~5 points in pull requests
44+
<br />
45+
~15 points total
46+
<br />2 of 4 consecutive active months
47+
</td>
48+
<td>~10 points</td>
49+
<td>~1 share / active month</td>
50+
</tr>
51+
<tr>
52+
<th>Maintainer</th>
53+
<td>
54+
~10 points in issues
55+
<br />
56+
~10 points in pull requests
57+
<br />
58+
~30 points total
59+
<br />3 of 6 active months
60+
</td>
61+
<td>~20 points</td>
62+
<td>~2 shares / active month</td>
63+
</tr>
64+
</tbody>
65+
</table>
66+
67+
:::note
68+
We treat everything here as approximate numbers.
69+
We're a small enough team to informally discuss changes ad hoc and allow off-by-one-or-two months.
70+
:::
71+
72+
## Pointing
73+
74+
Although it's impossible to accurately estimate software projects, we want to roughly establish expectations of effort+time spent on the tiers.
75+
These are all rough estimations and should be taken as approximate starting guides to consider.
76+
77+
We treat both the creation and review of issues and PRs along the rough scale of:
78+
79+
<table>
80+
<thead>
81+
<tr>
82+
<th>Size</th>
83+
<th>Description</th>
84+
<th>Points</th>
85+
<th>Examples</th>
86+
</tr>
87+
</thead>
88+
<tbody>
89+
<tr>
90+
<th>Trivial</th>
91+
<td>Small typos or single-file bugfixes</td>
92+
<td>1</td>
93+
<td>
94+
<a href="https://github.com/typescript-eslint/typescript-eslint/pull/6976">
95+
#6976
96+
</a>
97+
, <a href="https://github.com/typescript-eslint/typescript-eslint/issues/6992">#6992</a>
98+
</td>
99+
</tr>
100+
<tr>
101+
<th>Straightforward</th>
102+
<td>2-3 files at most, with minimal logical changes</td>
103+
<td>2</td>
104+
<td>
105+
<a href="https://github.com/typescript-eslint/typescript-eslint/pull/6780">
106+
#6780
107+
</a>
108+
, <a href="https://github.com/typescript-eslint/typescript-eslint/pull/6910">#6910</a>
109+
</td>
110+
</tr>
111+
<tr>
112+
<th>Large</th>
113+
<td>Multi-file logical changes that require real review+thought</td>
114+
<td>3</td>
115+
<td>
116+
<a href="https://github.com/typescript-eslint/typescript-eslint/pull/6107">
117+
#6107
118+
</a>
119+
, <a href="https://github.com/typescript-eslint/typescript-eslint/pull/6907">#6907</a>
120+
</td>
121+
</tr>
122+
<tr>
123+
<th>Unusual</th>
124+
<td>Dozen+ file logical changes that require deep investigation</td>
125+
<td>≥5*</td>
126+
<td>
127+
<a href="https://github.com/typescript-eslint/typescript-eslint/pull/6084">
128+
#6084
129+
</a>
130+
, <a href="https://github.com/typescript-eslint/typescript-eslint/pull/6777">#6777</a>
131+
</td>
132+
</tr>
133+
</tbody>
134+
</table>
135+
136+
> \*Unusually large efforts may be >5 points at maintainer discretion depending on time spent.
137+
138+
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.
139+
140+
## Advancement
141+
142+
Each tier corresponds to a role on Discord and GitHub.
143+
When you first hit a tier, you can post in the [`#roles` channel on Discord](https://discord.com/channels/1026804805894672454/1184219870691328051).
144+
145+
We will confirm privately that you've hit the intent of the contribution tiers.
146+
We'll then grant you the role on Discord and GitHub and profusely thank you for everything you've done. ❤️
147+
148+
### Recognition
149+
150+
Depending on the tier you reach, you can also provide information for an upcoming _Team_ page:
151+
152+
- Contributor and Code Contributor: Preferred photo, name, social media handles
153+
- Committer and Maintainer: ~2 paragraph bio of yourself
154+
155+
See existing bios for examples of what to put.
156+
157+
:::note
158+
You can decline to opt into the Discord role or site recognition, and you can always opt out after the fact.
159+
Nothing is mandatory.
160+
We just like including recognition as thanks for working with us. 💕
161+
:::
162+
163+
## Reimbursement
164+
165+
Team members will be reimbursed the minimum of their activity level and their tier.
166+
Each month:
167+
168+
- Committers and maintainers who hit their expectation receive their full shares
169+
- Committers and maintainers who hit roughly half their expectation receive half shares
170+
171+
Reimbursements are generally handled through [our Open Collective page](https://opencollective.com/typescript-eslint).
172+
173+
### Community Reimbursements
174+
175+
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.
176+
177+
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.

‎docs/maintenance/Governance.mdx

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
id: governance
3+
title: Governance
4+
---

‎docs/maintenance/Issues.mdx

+19-8
Original file line numberDiff line numberDiff line change
@@ -5,14 +5,25 @@ title: Issues
55

66
This document serves as a guide for how you might manage our [GitHub Issues](https://docs.github.com/issues), also known as issue triaging.
77

8-
Use your best judgement when triaging issues, and most of all remember to be **kind, friendly, and encouraging** when responding to users.
8+
Use your best judgement when triaging issues, and most of all remember to be **encouraging, friendly, and kind** when responding to users.
99
Many users are new to open source and/or typed linting.
1010
It's imperative we give them a positive, uplifting experience.
1111

1212
:::tip
1313
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!
1414
:::
1515

16+
## Governance
17+
18+
Per the scales from [Contribution Tiers > Pointing](./Contributor_Tiers.mdx#pointing):
19+
20+
- Straightforward: at reviewer discretion, may be marked as approved by any committer or maintainer.
21+
This includes docs enhancements, bug fixes, and feature additions.
22+
- Non-straightforward: may be marked as approved with either two committer approvals or one maintainer approval.
23+
These include significant internal refactors and non-breaking public API changes.
24+
- "Unusual"-categorized: require a public discussion followed by two maintainer approvals.
25+
These include significant refactors with cross-project and public API ramifications.
26+
1627
## Issue Flow
1728

1829
:::note
@@ -21,17 +32,17 @@ Don't treat these as exact responses you must use: they're just a starting copy+
2132
Please do adopt your specific responses to your personal tone and to match the thread for non-straightforward issues.
2233
:::
2334

24-
[Issues pending triage](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aopen+is%3Aissue+label%3Atriage) are searchable the `triage` label.
35+
[Issues pending triage](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aopen+is%3Aissue+label%3Atriage) are searchable with the `triage` label.
2536
That label is added automatically when a new issue is created.
2637
Most issues go through the following review flow when created or updated:
2738

2839
1. A maintainer ensures the issue is valid:
2940
- If the poster didn't fill out an appropriate template with enough information:
30-
- Add the `please fill out the template` and `awaiting response` labels
41+
- Add the `please fill out the template` and `awaiting response` labels, and remove the `triage` label
3142
- Ask the poster for more information using a _Needs More Info_ response
3243
- If it's a duplicate of an issue that already exists:
33-
- Add the `duplicate` label and remove the `bug` label
34-
- If it's an obvious duplicate, post a _Clearly Duplicate Issue_ response
44+
- Add the `duplicate` label and remove the `triage` label
45+
- If it's an obvious duplicate, post a _Clearly Duplicate Issue_ response linking to the existing issue
3546
- If it's not an obvious duplicate, link to the existing issue and explain why
3647
- If the code is working as intended:
3748
- 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://
135146
Our flow for issues that have been waiting for >=1 month is:
136147

137148
1. Ping the author with a message like the _Checking In_ template
138-
2. Add the `stale` label to the issue
139-
3. Wait 2 weeks
140-
4. If they still haven't responded, close the issue with a message like the _Pruning Stale Issue_ template
149+
1. Add the `stale` label to the issue
150+
1. Wait 2 weeks
151+
1. If they still haven't responded, close the issue with a message like the _Pruning Stale Issue_ template

‎docs/maintenance/Pull_Requests.mdx

+11
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,17 @@ It's imperative we give them a positive, uplifting experience.
1313
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!
1414
:::
1515

16+
## Governance
17+
18+
Per the scales from [Contribution Tiers > Pointing](./Contributor_Tiers.mdx#pointing):
19+
20+
- Straightforward: At reviewer discretion, may be merged with a single approval by any committer or maintainer.
21+
This includes docs enhancements, bug fixes, and feature additions.
22+
- Non-straightforward: may be merged with either two committer approvals or one maintainer approval.
23+
These include multi-package internal refactors and non-breaking public API changes.
24+
- "Unusual"-categorized: require two maintainer approvals.
25+
These include significant refactors with cross-project and public API ramifications.
26+
1627
## PR Flow
1728

1829
:::note

‎docs/maintenance/Major_Release_Steps.mdx renamed to ‎docs/maintenance/Releases.mdx

+27-8
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,18 @@
11
---
2-
id: major-release-steps
3-
title: Major Release Steps
2+
id: releases
3+
title: Releases
44
---
55

6-
## 1. Pre-Release Preparation
6+
[Users > Releases](../users/Releases.mdx) describes how our automatic releases are done.
7+
There is generally no maintenance activity we need to take for the weekly releases.
8+
9+
However, there are two kinds of releases we infrequently go through that each require manual effort.
10+
11+
## Major Releases
12+
13+
Per [Users > Releases > Major Releases](../users/Releases.mdx#major-releases), we infrequently release major versions with accumulated breaking changes.
14+
15+
### 1. Pre-Release Preparation
716

817
1. Create a milestone by the name of the release [example: [Milestone 6.0.0](https://github.com/typescript-eslint/typescript-eslint/milestone/8)].
918
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
1827
- Its publish command should be `npx lerna publish premajor --loglevel=verbose --canary --exact --force-publish --yes --dist-tag rc-v${major}`.
1928
- Merge this into `main` once reviewed and rebase the `v${major}` branch.
2029

21-
## 2. Merging Breaking Changes
30+
### 2. Merging Breaking Changes
2231

2332
1. Send a PR from `v${major}` to `main` [example: [v6.0.0](https://github.com/typescript-eslint/typescript-eslint/pull/5886)].
2433
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.
3443
They don't need any special treatment.
3544
:::
3645

37-
## 3. Releasing the Version
46+
### 3. Releasing the Version
3847

39-
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.
48+
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.
4049
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.
50+
- 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)
51+
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!
4152

42-
- 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)
53+
## Out-of-Band Releases
4354

44-
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!
55+
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.
56+
If that happens:
57+
58+
1. Mention in any relevant issue(s) that you intend to release an out-of-band release
59+
1. Post in a private maintenance Discord channel that you're working on it
60+
1. Send a pull request resolving the issue(s)
61+
1. Waiting up to a day (as reasonable) for approval before merging the PR
62+
1. Trigger the private release workflow to cause a new release
63+
1. Post back in those same issue(s) with a link to the newly released version(s)

‎docs/maintenance/Dependency_Version_Upgrades.mdx renamed to ‎docs/maintenance/pull-requests/Dependency_Version_Upgrades.mdx

+3-3
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ Whenever you discover any new areas of work that are blocked by dropping an old
3131
1. Upgrade the root `package.json` `devDependency` to the latest ESLint
3232
1. Add the new major version to the explicit `peerDependency` versions
3333
1. Check [`eslint-visitor-keys`](https://www.npmjs.com/package/eslint-visitor-keys) for a new version to be upgraded to as well.
34-
1. Update [Users > Dependency Versions > ESLint](../users/Dependency_Versions.mdx#eslint)
34+
1. Update [Users > Dependency Versions > ESLint](../../users/Dependency_Versions.mdx#eslint)
3535

3636
### Removing Support for an Old ESLint Version
3737

@@ -42,7 +42,7 @@ Whenever you discover any new areas of work that are blocked by dropping an old
4242
- `/eslint.*5/i`
4343
- `/todo.*eslint.*5/i`
4444
- `/todo.*eslint/i`
45-
1. Update [Users > Dependency Versions > ESLint](../users/Dependency_Versions.mdx#eslint)
45+
1. Update [Users > Dependency Versions > ESLint](../../users/Dependency_Versions.mdx#eslint)
4646

4747
See [chore: drop support for ESLint v6](https://github.com/typescript-eslint/typescript-eslint/pull/5972) for reference.
4848

@@ -115,7 +115,7 @@ A single PR can remove support for old TypeScript versions as a breaking change:
115115
1. Update the root `package.json` `devDependency`
116116
1. Update the `SUPPORTED_TYPESCRIPT_VERSIONS` constant in `warnAboutTSVersion.ts`
117117
1. Update the `versions` constant in `version-check.ts`
118-
1. Update [Users > Dependency Versions > TypeScript](../users/Dependency_Versions.mdx#typescript)
118+
1. Update [Users > Dependency Versions > TypeScript](../../users/Dependency_Versions.mdx#typescript)
119119
1. Search for source code comments (excluding `CHANGELOG.md` files) that mention a now-unsupported version of TypeScript.
120120
- For example, to remove support for v4.3, searches might include:
121121
- `4.3`

‎docs/users/Dependency_Versions.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -55,4 +55,4 @@ See: [Packages > Parser > `warnOnUnsupportedTypeScriptVersion`](../packages/Pars
5555

5656
## Dependant Version Upgrades
5757

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

‎docs/users/Releases.mdx

+2-2
Original file line numberDiff line numberDiff line change
@@ -73,9 +73,9 @@ We currently do not have a set schedule around when major releases shall be perf
7373
We keep a backlog of breaking issues as a milestone on GitHub that is named in the form `${major}.0.0`.
7474
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.
7575

76-
See [Maintenance > Major Release Steps](../maintenance/Major_Release_Steps.mdx) for steps to perform a major release.
76+
See [Maintenance > Releases](../maintenance/Releases.mdx#major-releases) for steps to perform a major release.
7777

78-
## Out-of-Band
78+
## Out-of-Band Releases
7979

8080
We will do releases "out-of-band" (outside the [latest](#latest) schedule) for rare emergencies.
8181
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.

0 commit comments

Comments
 (0)