typescript-eslint · JoshuaKGoldberg · Oct 4, 2022 · Oct 2, 2022 · Oct 2, 2022 · Oct 4, 2022
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,86 +1,71 @@
 # Contributing
 
-## Raising Issues
-
-Feel free to raise an issue if you have a question, an enhancement, or a bug report.
+Thank you for your interest in contributing to TypeScript ESLint! 💜
 
-Use the issue search functionality to search all **_opened and closed_** [issues](https://github.com/typescript-eslint/typescript-eslint/issues) before raising a new issue. If you raise a duplicate issue, you're just creating noise for everyone watching this repo.
+> Make sure you read our [Code of Conduct](./CODE_OF_CONDUCT.md) before contributing.
 
-Before raising a bug, ensure you are using the latest version of our packages. We release every week, so there's a good chance your issue might have already been fixed.
+## Raising Issues
 
-Finally, when raising a new issue, please fill out the [issue template](https://github.com/typescript-eslint/typescript-eslint/issues/new/choose) - **_please don't skip sections_**.
+So you've got a bug report, documentation request, or feature suggestion?
+Great!
 
-Please provide **_as much information as possible_**. This project is maintained by volunteers, so the more information you provide, the less likely we will have to waste everyone's time in asking you for more information.
+Do:
 
-If you have a particularly complex issue that can't be reproduced on [our playground](https://typescript-eslint.io/play) - consider creating a small, self-contained reproduction repo. This will help you in figuring out the exact problem, and will help us in reproducing and diagnosing the bug.
+- Make sure you're using the [latest version of our packages](https://github.com/typescript-eslint/typescript-eslint/releases)
+- Search [all opened and closed issues](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aissue+) to make sure your issue wouldn't be a duplicate
+- Fill out the [appropriate issue template](https://github.com/typescript-eslint/typescript-eslint/issues/new/choose) completely
+- Provide as much information as you can
 
-**_Help us to help you_**
+### Questions and Support Requests
 
-## Questions and requests for support
+We do not have the bandwidth to handle questions or support requests in the issue tracker.
+You can instead:
 
-Questions and requests for support should not be opened as issues and should be handled in the following ways:
+- Ask a question on [StackOverflow](https://stackoverflow.com/questions/tagged/typescript-eslint 'StackOverflow questions tagged with typescript-eslint') using the `typescript-eslint` tag
+- Publicly tweet [@tseslint on Twitter](https://twitter.com/tseslint)
 
-- Ask a question on [StackOverflow](https://stackoverflow.com/questions/tagged/typescript-eslint) using the `typescript-eslint` tag.
-- Publicly tweet [@tseslint on Twitter](https://twitter.com/tseslint).
+> Note that requests to add documentation _are_ allowed, even encouraged! 📝
 
 ## Commenting
 
-Feel free to comment on any open issue if you have more information that you feel like you can provide. If you don't have more information, instead use the "reaction" feature on the root comment for the issue. We use reactions to help gauge which issues are important to the community, so these are the best way to show us an issue is important.
+Please do comment on any open issue if you have more information that would be useful.
 
-Please refrain from leaving useless comments on issues. Comments like "+1", or "when's this getting fixed", or "any progress on this" just serve as spam, and annoy every single person subscribed to the issue. Generally we will just delete those comments, so save everyone time and think twice.
+Don't:
 
-Please refrain from commenting on old, closed issues and PRs. Your issue is rarely related enough to a closed issue to warrant "necroing" a dead thread - raising a new issue means you can fill in the [template](<(https://github.com/typescript-eslint/typescript-eslint/issues/new/choose)>), and make it easier for us to help you. Often times if you comment on a closed issue, we will just ask you to open a new issue, so please save everyone's time, and **_help us to help you_**.
+- Leave useless comments such as _"+1"_ or _"when's this getting fixed?"_ that only act as spam
+  - If you have nothing to add but enthusiasm and joy, add a reaction such as 👍
+- Bring up unrelated topics in existing issues: instead, file a new issue
+- Comment on closed PRs: instead, [file a new issue](#raising-issues)
+- Comment on commits directly, as those comments are not searchable: instead, file a new issue
 
-Please refrain from commenting on `main` commits. Commit comments are not searchable, meaning that nobody else can discover your comments. Raise an issue and reference the commit instead so that everyone can see your comment, and you can fill out the template.
+## Pull Requests
 
----
+> See [DEVELOPMENT.md](./DEVELOPMENT.md) for details on how to get started developing locally.
 
-## Pull Requests
+Do:
 
-> With the exception of extremely minor documentation typos, **only send pull requests that resolve open issues**.
-
-Anyone is free to help us build and maintain this project. If you see an issue that needs working on because it's important to you, comment on the issue to help make sure that nobody else works on it at the same time, and then start working.
-
-Developing in this repo is easy:
-
-- First fork the repo, and then clone it locally.
-- Create a new branch.
-- In the root of the project, run `yarn install`.
-  - This will install the dependencies, link the packages and do a build.
-- Make the required changes.
-
-### Validating Your Changes
-
-We have a sophisticated CI process setup which gets run on every PR. You must pass all of the checks for us to consider merging your PR. Here is a list of checks that are done automatically, that you can also perform locally before pushing.
-
-- Ensure your code is properly formatted.
-  - You can run `yarn format` in any package or in the root.
-  - Alternatively, you can run prettier on save.
-- Ensure there are no typechecking errors.
-  - You can run `yarn typecheck` in any package or in the root.
-- Ensure your changes are adequately tested.
-  - You can run `yarn test` in any package.
-    - [VS Code launch tasks](https://code.visualstudio.com/docs/editor/tasks) tasks are provided that allow [visual debugging](https://code.visualstudio.com/docs/editor/debugging) tests
-  - We aim for around `90%` branch coverage for every PR.
-  - Coverage reports should automatically be generated locally, and the `codecov` bot should also comment on your PR with the percentage, as well as links to the line-by-line coverage of each file touched by your PR.
-- Ensure you have no lint errors.
-  - You can run `yarn lint` in any package or in the root.
-  - You can run `yarn lint-markdown` in the root.
-- If you have made changes to any markdown documentation, ensure there are no spelling errors
-  - You can run `yarn check-spelling` in the root.
-  - Or if you are using vscode, you can use [`Code Spell Checker`](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker) plugin.
-- If you have made changes within the `eslint-plugin` package, ensure the configs and documentation are valid.
-  - You can run `yarn check-configs` and `yarn check-docs` in the root, or in the `eslint-plugin` folder.
+- Only send pull requests that resolve [open issues marked as `accepting prs`](https://github.com/typescript-eslint/typescript-eslint/issues?q=is%3Aissue+is%3Aopen+label%3A%22accepting+prs%22)
+  - One exception: extremely minor documentation typos
+- Fill out the pull request template in full
+- Validate your changes per [Development > Validating Changes](./DEVELOPMENT.md#validating-changes) before un-[drafting your PR](https://github.blog/2019-02-14-introducing-draft-pull-requests)
+
+Don't:
+
+- Force push after opening a PR
+  - Reasoning: GitHub is not able to track changes across force pushes, which makes it take longer for us to perform incremental reviews
+- Comment asking for updates
+  - Reasoning: Your PR hasn't been forgotten! The volunteer maintainers have limited time to work on the project, and they will get to it as soon as they are able.
 
 ### Raising a PR
 
-Once your changes are ready, you can raise a PR. The title of your PR should match the following format:
+Once your changes are ready, you can raise a PR! 🙌
+The title of your PR should match the following format:
 
 ```text
 <type>(<package>): <short description>
 ```
 
-You can find more samples of good past PR titles in [recent commits to `main`](https://github.com/typescript-eslint/typescript-eslint/commits/main))
+You can find more samples of good past PR titles in [recent commits to `main`](https://github.com/typescript-eslint/typescript-eslint/commits/main).
 
 ```text
 fix(scope-manager): correct handling for class static blocks
@@ -90,36 +75,36 @@ fix(scope-manager): correct handling for class static blocks
 docs: Fix links to getting started in README.md
 ```
 
-### Type
+Within the body of your PR, make sure you reference the issue that you have worked on, as well as pointing out anything of note you wish us to look at during our review.
+
+> We do not care about the number, or style of commits in your history, because we squash merge every PR into `main`.
+> Feel free to commit in whatever style you feel comfortable with.
+
+#### type
 
 Must be one of the following:
 
+- `docs` - if you only change documentation, and not shipped code
 - `feat` - for any new functionality additions
 - `fix` - for any bug fixes that don't add new functionality
 - `test` - if you only change tests, and not shipped code
-- `docs` - if you only change documentation, and not shipped code
 - `chore` - anything else
 
-### package
+#### package
 
-`<package>` is the name of the package you have made changes within (`eslint-plugin`, `parser`, `typescript-estree`, etc). If you make significant changes across multiple packages, you can omit this (i.e. `feat: foo bar`).
+The name of the package you have made changes within, (e.g. `eslint-plugin`, `parser`, `typescript-estree`).
+If you make significant changes across multiple packages, you can omit this (e.g.
+`feat: foo bar`).
 
-### short description
+#### short description
 
-And `<short description>` is a succinct title for the PR.
-
-Within the body of your PR, make sure you reference the issue that you have worked on, as well as pointing out anything of note you wish us to look at during our review.
-
-Make sure you use the "Fixes #xxx" format to reference issues, so that GitHub automatically closes the issues when we merge the PR. Also note that if you are fixing multiple issues at once, you can only reference one issue per line, and must put one "Fixes #xxx" per issue number.
-
-In terms of your commit history - we do not care about the number, or style of commits in your history, because we squash merge every PR into `main`. Feel free to commit in whatever style you feel comfortable with.
-
-**_One thing we ask is to please avoid force pushing after you have raised a PR_**. GitHub is not able to track changes across force pushes, which makes it impossible to efficiently do incremental reviews. This slows us down, and means it will take longer for us to get your PR merged.
+A succinct title for the PR.
 
 ### Addressing Feedback and Beyond
 
-With your PR raised, and the CI showing green, your PR will [sit in the queue to be reviewed](https://github.com/typescript-eslint/typescript-eslint/pulls?q=is%3Apr+is%3Aopen+sort%3Acreated-asc+-label%3A%22breaking+change%22+-label%3A%22awaiting+response%22+-label%3A%221+approval%22+-label%3A%22DO+NOT+MERGE%22). We generally review PRs oldest to newest, unless we consider a newer PR higher priority (i.e. if it's a bug fix).
-
-Please note that as this project is maintained by volunteers, it may take a while for us to get around to your PR (sometimes a month or more). Be patient, we'll get to it. Please refrain from commenting asking for a review, or similar bump comments. **_These just create spam for maintainers, and does not push your PR higher in the queue_**.
+With your PR raised and the CI passing, your PR will [wait in the queue to be reviewed](https://github.com/typescript-eslint/typescript-eslint/pulls?q=is%3Apr+is%3Aopen+sort%3Acreated-asc+-label%3A%22breaking+change%22+-label%3A%22awaiting+response%22+-label%3A%221+approval%22+-label%3A%22DO+NOT+MERGE%22+status%3Asuccess).
+We generally review PRs oldest to newest, unless we consider a newer PR higher priority (e.g. if it's a bug fix).
 
-Once we have reviewed your PR, we will provide any feedback that needs addressing. If you feel a requested change is wrong, don't be afraid to discuss with us in the comments. Once the feedback is addressed, and the PR is reviewed, we'll ensure the branch is up to date with `main`, and merge it for you.
+Once we have reviewed your PR, we will provide any feedback that needs addressing.
+If you feel a requested change is wrong, don't be afraid to discuss with us in the comments.
+Once the feedback is addressed, and the PR is reviewed, we'll ensure the branch is up to date with `main`, and merge it for you.
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
@@ -0,0 +1,69 @@
+# Development
+
+Thank you for your interest in developing on TypeScript ESLint! ❤️‍🔥
+
+> See [CONTRIBUTING.md](./CONTRIBUTING.md) for details on our general contribution flows.
+
+## Setup
+
+After [forking the repo from GitHub](https://help.github.com/articles/fork-a-repo):
+
+```shell
+git clone https://github.com/<your-name-here>/typescript-eslint
+cd typescript-eslint
+yarn
+```
+
+Postinstall scripts will then fully build your repository locally with (`yarn build`).
+At this point, you're ready to develop! 🚀
+
+## Builds
+
+You can run `yarn build` in any package or in the root to build the package(s).
+
+Keep in mind that packages generally depend on each other's built outputs, and you'll need to `yarn build` dependents for their consumers to receive any new local changes.
+For example, if you make a change within `scope-manager` and want to use it in `eslint-plugin`, you'll need to `yarn build` either from the root or within `packages/scope-manager`.
+
+## Validating Changes
+
+The following checks are all run on pull requests automatically.
+You can also perform them locally.
+
+### Formatting
+
+We use [Prettier](https://prettier.io) to auto-format code.
+A Git pre-commit hook should apply it to all committed changes.
+ALternately, you can run `yarn format` in any package or in the root.
+
+### Linting
+
+All code changes must pass ESLint.
+You can run `yarn lint` in any package or in the root.
+
+### Proofreading
+
+Changes must pass two linters for documentation and naming, the commands for which may be run from the root:
+
+- `yarn check-spelling`: [CSpell](https://cspell.org), for all code
+- `yarn lint-markdown`: [Markdownlint](https://github.com/DavidAnson/markdownlint), for Markdown documentation
+
+### Tests
+
+All code changes should ideally be unit tested if possible.
+You can run `yarn test` in any package to run its tests.
+
+> [VS Code launch tasks](https://code.visualstudio.com/docs/editor/tasks) tasks are provided that allow [visual debugging](https://code.visualstudio.com/docs/editor/debugging) tests
+
+#### Code Coverage
+
+We aim for 100% code coverage in all PRs when possible, except in the `website/` package.
+Coverage reports are be generated locally whenever `yarn test` is run.
+
+The `codecov` bot should also comment on your PR with the percentage, as well as links to the line-by-line coverage of each file touched by your PR.
+
+### Type Checking
+
+All code should pass TypeScript type checking.
+You can run `yarn typecheck` in any package or in the root to run `tsc`.
+
+> Run `yarn typecheck -w` to start `tsc` in watch mode.