docs: linting onboarding guides (typescript-eslint#1324)

Author: bradzacher

.spelling

@@ -0,0 +1,126 @@
+# markdown-spellcheck spelling configuration file
+# Format - lines beginning # are comments
+# global dictionary is at the start, file overrides afterwards
+# one word per line, to define a file override use ' - filename'
+# where filename is relative to this configuration file
+1000s
+1pm
+30s
+A11y
+Airbnb
+Airbnb's
+ands
+API
+APIs
+ASI
+AST
+ASTs
+async
+autofixers
+backticks
+boolean
+booleans
+camelCase
+camelCasing
+CLI
+codebase
+codebases
+CommonJS
+config
+configs
+const
+Crockford
+declarators
+destructure
+destructured
+destructuring
+e.g.
+enum
+enums
+ES2015
+ES2016
+ES5
+ES6
+ESLint
+ESLint's
+eslintrc.js
+ESTree
+fallthrough
+falsy
+filenames
+heavy_check_mark
+i.e.
+IIFE
+IIFEs
+ing
+jQuery
+JS
+JSCS
+JSHint
+JSON
+JSX
+linebreak
+linters
+MDN
+monorepo
+monorepos
+multiline
+namespace
+namespaces
+natively
+necroing
+NodeJS
+npm
+nullish
+OOM
+OOMs
+onboard
+OSS
+package.json
+Palantir
+PascalCase
+PascalCased
+performant
+pluggable
+pre-ES6
+pre-parse
+pre-releases
+premade
+README
+readonly
+realtime
+RegExp#exec
+reimplement
+repo
+roadmap
+ruleset
+rulesets
+runtime
+searchable
+String#match
+substring
+substrings
+superset
+supertype
+syntaxes
+thenable
+thought_balloon
+timelines
+TODO
+transpile
+truthy
+tsconfig
+tsconfig.json
+tsconfigs
+TSLint
+typecheck
+typechecker
+typechecking
+TypeScript
+typings
+unfixable
+unprefixed
+untyped
+VSCode
+Vue
+whitespace

CONTRIBUTING.md

@@ -0,0 +1,92 @@
+# Contributing
+
+## Raising Issues
+
+Feel free to raise an issue if you have a question, an enhancement, or a bug report.
+
+Please ensure you use the issue search functionality to search all **_opened and closed_** issues before raising a new issue.
+
+When raising a new issue, please fill out the issue template - please don't skip sections.
+Please provide **_as much information as possible_**. This project is maintained by volunteers, so the more the more information you provide, the less likely we will have to waste everyone's time in asking you for more information.
+
+**_Help us to help you_**
+
+## 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 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.
+
+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, 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_**.
+
+Please refrain from commenting on `master` 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
+
+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.
+  - 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.
+- If you have made changes to any markdown documentation, ensure there are no spelling errors
+  - You can run `yarn check:spelling` in the root.
+- 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.
+
+### Raising a PR
+
+Once your changes are ready, you can raise a PR. The title of your PR should match the following format:
+
+```
+<tag>(<package>): <short description>
+```
+
+Where `<tag>` is one of:
+
+- `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
+
+And `<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`).
+
+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 a 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 master. 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.
+
+### 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_**.
+
+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 master, and merge it for you.

README.md

@@ -19,12 +19,12 @@
 - [What are ESLint and TypeScript, and how do they compare?](#what-are-eslint-and-typescript-and-how-do-they-compare)
 - [Why does this project exist?](#why-does-this-project-exist)
 - [What about TSLint?](#what-about-tslint)
-- [How does typescript-eslint work and why do you have multiple packages?](#how-does-typescript-eslint-work-and-why-do-you-have-multiple-packages)
+- [How does `typescript-eslint` work and why do you have multiple packages?](#how-does-typescript-eslint-work-and-why-do-you-have-multiple-packages)
 - [Can I use all of the existing ESLint plugins and rules without any changes?](#can-i-use-all-of-the-existing-eslint-plugins-and-rules-without-any-changes)
 - [Can we write rules which leverage type information?](#can-we-write-rules-which-leverage-type-information)
-- [What about Babel and babel-eslint?](#what-about-babel-and-babel-eslint)
+- [What about Babel and `babel-eslint`?](#what-about-babel-and-babel-eslint)
 - [How can I help?](#how-can-i-help)
-- [How do I configure my project to use typescript-eslint?](#how-do-i-configure-my-project-to-use-typescript-eslint)
+- [Packages included in this project?](#packages-included-in-this-project)
 - [Package Versions](#package-versions)
 - [Supported TypeScript Version](#supported-typescript-version)
 - [Supported ESLint version](#supported-eslint-version)
@@ -34,11 +34,12 @@
 
 ## Getting Started
 
-The following sections will give you an overview of what this project is, why it exists and how it works at a high level.
+**[You can find our Getting Started docs here](./docs/getting-started/README.md)**
+**[You can find our Linting FAQ / Troubleshooting docs here](./docs/getting-started/linting/FAQ.md)**
 
-**It is very important that you are familiar with these concepts before reporting issues**, so please read them and let us know if you have any feedback.
+The documentation below will give you an overview of what this project is, why it exists and how it works at a high level.
 
-If you are ready to get started you can jump to the package READMEs from here: [#how-do-i-configure-my-project-to-use-typescript-eslint](#how-do-i-configure-my-project-to-use-typescript-eslint)
+**It is very important that you are familiar with these concepts before reporting issues**, so it is a good idea to read them before raising issues.
 
 <br>
 
@@ -195,12 +196,10 @@ All positive contributions are welcome here!
 
 <br>
 
-## How do I configure my project to use `typescript-eslint`?
+## Packages included in this project
 
 Please follow the links below for the packages you care about.
 
-If you are interested in using TypeScript and ESLint together, you will want to check out [`@typescript-eslint/parser`](./packages/parser/) and [`@typescript-eslint/eslint-plugin`](./packages/eslint-plugin/) at the very least:
-
 - [`@typescript-eslint/typescript-estree`](./packages/typescript-estree/) - An entirely generic TypeScript parser which takes TypeScript source code and produces an <a href="https://github.com/estree/estree">ESTree</a>-compatible AST</p>
 
   - This package is also used to power the amazing opinionated code formatter [Prettier](https://prettier.io)'s own TypeScript use-case.
@@ -229,7 +228,7 @@ The latest version under the `canary` tag **(latest commit to master)** is:
 
 <a href="https://www.npmjs.com/package/@typescript-eslint/parser"><img src="https://img.shields.io/npm/v/@typescript-eslint/parser/canary.svg?style=flat-square" alt="NPM Version" /></a>
 
-(Note: The only exceptions to the automated publishes described above are when we are in the final phases of creating the next major version of the libraries - e.g. going from 1.x.x to 2.x.x. During these periods, we manually publish `canary` releases until we are happy with the release and promote it to `latest`.)
+(Note: The only exceptions to the automated publishes described above are when we are in the final phases of creating the next major version of the libraries - e.g. going from `1.x.x` to `2.x.x`. During these periods, we manually publish `canary` releases until we are happy with the release and promote it to `latest`.)
 
 <br>
 

azure-pipelines.yml

@@ -35,6 +35,10 @@ jobs:
           yarn check:docs
         displayName: 'Validate documentation'
 
+      - script: |
+          yarn check:spelling
+        displayName: 'Validate documentation spelling'
+
       - script: |
           yarn check:configs
         displayName: 'Validate plugin configs'
@@ -80,8 +84,8 @@ jobs:
   - job: publish_canary_version
     displayName: Publish the latest code as a canary version
     dependsOn:
-    - primary_code_validation_and_tests
-    - unit_tests_on_other_node_versions
+      - primary_code_validation_and_tests
+      - unit_tests_on_other_node_versions
     condition: and(succeeded(), eq(variables['Build.SourceBranchName'], 'master'), ne(variables['Build.Reason'], 'PullRequest'))
     pool:
       vmImage: 'Ubuntu-16.04'

docs/getting-started/README.md

@@ -0,0 +1,11 @@
+# Getting Started
+
+Approaching a monorepo project like this can be pretty daunting and hard to navigate for a new user.
+
+The goal of these docs are to give you a quick overview of the project and all of its the pieces, as well as provide guides to help you get setup.
+
+The docs are broken down into the following categories:
+
+### [I want to lint my TypeScript codebase.](./linting/README.md)
+
+### [(TODO) I want to write an ESLint plugin in TypeScript.](./plugin-development/README.md)

docs/getting-started/linting/FAQ.md

@@ -0,0 +1,83 @@
+# Troubleshooting / FAQ
+
+## Table of Contents
+
+- [My linting seems really slow](#my-linting-seems-really-slow)
+- [I get errors telling me "The file must be included in at least one of the projects provided"](#i-get-errors-telling-me-"the-file-must-be-included-in-at-least-one-of-the-projects-provided")
+- [I use a framework (like Vue) that requires custom file extensions, and I get errors like "You should add `parserOptions.extraFileExtensions` to your config"](<#i-use-a-framework-(like-vue)-that-requires-custom-file-extensions,-and-i-get-errors-like-"you-should-add-`parserOptions.extraFileExtensions`-to-your-config">)
+
+---
+
+## My linting feels really slow
+
+As mentioned in the [type-aware linting doc](./TYPED_LINTING.md), if you're using type-aware linting, your lint times should be roughly the same as your build times.
+
+If you're experiencing times much slower than that, then there are a few common culprits.
+
+### Wide includes in your `tsconfig`
+
+When using type-aware linting, you provide us with one or more tsconfigs. We then will pre-parse all files so that full and complete type information is available.
+
+If you provide very wide globs in your `include` (like `**/*`), it can cause many more files than you expect to be included in this pre-parse. Additionally, if you provide no `include` in your tsconfig, then it is the same as providing the widest glob.
+
+Wide globs can cause TypeScript to parse things like build artifacts, which can heavily impact performance. Always ensure you provide globs targeted at the folders you are specifically wanting to lint.
+
+### `eslint-plugin-prettier`
+
+This plugin surfaces prettier formatting problems at lint time, helping to ensure your code is always formatted. However this comes at a quite a large cost - in order to figure out if there is a difference, it has to do a prettier format on every file being linted. This means that each file will be parsed twice - once by ESLint, and once by Prettier. This can add up for large codebases.
+
+Instead of using this plugin, we recommend using prettier's `--list-different` flag to detect if a file has not been correctly formatted. For example, our CI is setup to run the following command automatically, which blocks diffs that have not been formatted:
+
+```bash
+$ yarn prettier --list-different \"./**/*.{ts,js,json,md}\"
+```
+
+### `eslint-plugin-import`
+
+This is another great plugin that we use ourselves in this project. However there are a few rules which can cause your lints to be really slow, because they cause the plugin to do its own parsing, and file tracking. This double parsing adds up for large codebases.
+
+There are many rules that do single file static analysis, but we provide the following recommendations.
+
+We recommend you do not use the following rules, as TypeScript provides the same checks as part of standard type checking:
+
+- `import/named`
+- `import/namespace`
+- `import/default`
+- `import/no-named-as-default-member`
+
+The following rules do not have equivalent checks in TypeScript, so we recommend that you only run them at CI/push time, to lessen the local performance burden.
+
+- `import/no-named-as-default`
+- `import/no-cycle`
+- `import/no-unused-modules`
+- `import/no-deprecated`
+
+### The `indent` / `@typescript-eslint/indent` rules
+
+This rule helps ensure your codebase follows a consistent indentation pattern. However this involves a _lot_ of computations across every single token in a file. Across a large codebase, these can add up, and severely impact performance.
+
+We recommend not using this rule, and instead using a tool like [`prettier`](https://www.npmjs.com/package/) to enforce a standardized formatting.
+
+---
+
+## I get errors telling me "The file must be included in at least one of the projects provided"
+
+This error means that the file that's being linted is not included in any of the tsconfig files you provided us. A lot of the time this happens when users have test files or similar that are not included.
+
+To fix this, simply make sure the `include` option in your tsconfig includes every single file you want to lint.
+
+---
+
+## I use a framework (like Vue) that requires custom file extensions, and I get errors like "You should add `parserOptions.extraFileExtensions` to your config"
+
+You can use `parserOptions.extraFileExtensions` to specify an array of non-TypeScript extensions to allow, for example:
+
+```diff
+ parserOptions: {
+   tsconfigRootDir: __dirname,
+   project: ['./tsconfig.json'],
++  extraFileExtensions: ['.vue'],
+ },
+```
+
+---