From 071e5a04d09d0dbf1d57e5835c4957fd04641e55 Mon Sep 17 00:00:00 2001 From: Brad Zacher Date: Fri, 22 May 2020 11:44:40 -0700 Subject: [PATCH] docs: various updates based on v3 feedback (#2070) --- docs/getting-started/linting/FAQ.md | 44 +++++++++++++++++++ docs/getting-started/linting/MONOREPO.md | 1 - docs/getting-started/linting/README.md | 3 -- docs/getting-started/linting/TYPED_LINTING.md | 1 - .../rules/explicit-module-boundary-types.md | 5 +++ .../docs/rules/naming-convention.md | 20 +++++++++ packages/eslint-plugin/src/configs/README.md | 25 +++++++++-- 7 files changed, 90 insertions(+), 9 deletions(-) diff --git a/docs/getting-started/linting/FAQ.md b/docs/getting-started/linting/FAQ.md index 33410ed3c46..799b7b626ba 100644 --- a/docs/getting-started/linting/FAQ.md +++ b/docs/getting-started/linting/FAQ.md @@ -11,6 +11,10 @@ --- +
+
+
+ ## 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. @@ -61,8 +65,16 @@ This rule helps ensure your codebase follows a consistent indentation pattern. H 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. @@ -78,8 +90,16 @@ There are a couple of solutions to this, depending on what you want to achieve. - Check the `include` option of each of the tsconfigs that you provide to `parserOptions.project` - you must ensure that all files match an `include` glob, or else our tooling will not be able to find it. - If your file shouldn't be a part of one of your existing tsconfigs (for example, it is a script/tool local to the repo), then consider creating a new tsconfig (we advise calling it `tsconfig.eslint.json`) in your project root which lists this file in its `include`. +
+
+
+ --- +
+
+
+ ## 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: @@ -92,8 +112,16 @@ You can use `parserOptions.extraFileExtensions` to specify an array of non-TypeS }, ``` +
+
+
+ --- +
+
+
+ ## I am using a rule from ESLint core, and it doesn't work correctly with TypeScript code This is a pretty common thing because TypeScript adds new features that ESLint doesn't know about. @@ -111,16 +139,32 @@ The first step is to [check our list of "extension" rules here](../../../package If you don't find an existing extension rule, or the extension rule doesn't work for your case, then you can go ahead and check our issues. [The contributing guide outlines the best way to raise an issue](../../../CONTRIBUTING.md#raising-issues). +
+
+
+ --- +
+
+
+ ## One of my lint rules isn't working correctly on a pure JavaScript file This is to be expected - ESLint rules do not check file extensions on purpose, as it causes issues in environments that use non-standard extensions (for example, a `.vue` and a `.md` file can both contain TypeScript code to be linted). If you have some pure JavaScript code that you do not want to apply certain lint rules to, then you can use [ESLint's `overrides` configuration](https://eslint.org/docs/user-guide/configuring#configuration-based-on-glob-patterns) to turn off certain rules, or even change the parser based on glob patterns. +
+
+
+ --- +
+
+
+ ## TypeScript should be installed locally Make sure that you have installed TypeScript locally i.e. by using `npm install typescript`, not `npm install -g typescript`, diff --git a/docs/getting-started/linting/MONOREPO.md b/docs/getting-started/linting/MONOREPO.md index 00200300f5d..30669920d83 100644 --- a/docs/getting-started/linting/MONOREPO.md +++ b/docs/getting-started/linting/MONOREPO.md @@ -28,7 +28,6 @@ For example, this is how we specify all of our `tsconfig.json` within this repo. plugins: ['@typescript-eslint'], extends: [ 'eslint:recommended', - 'plugin:@typescript-eslint/eslint-recommended', 'plugin:@typescript-eslint/recommended', 'plugin:@typescript-eslint/recommended-requiring-type-checking', ], diff --git a/docs/getting-started/linting/README.md b/docs/getting-started/linting/README.md index bb1fd058e89..0d699b19505 100644 --- a/docs/getting-started/linting/README.md +++ b/docs/getting-started/linting/README.md @@ -102,7 +102,6 @@ To use one of these complete config packages, you would replace the `extends` wi ], extends: [ - 'eslint:recommended', -- 'plugin:@typescript-eslint/eslint-recommended', - 'plugin:@typescript-eslint/recommended', + 'airbnb-typescript', ], @@ -124,7 +123,6 @@ Using this config is as simple as adding it to the end of your `extends`: ], extends: [ 'eslint:recommended', - 'plugin:@typescript-eslint/eslint-recommended', 'plugin:@typescript-eslint/recommended', + 'prettier/@typescript-eslint', ], @@ -153,7 +151,6 @@ Every plugin that is out there includes documentation on the various rules they ], extends: [ 'eslint:recommended', - 'plugin:@typescript-eslint/eslint-recommended', 'plugin:@typescript-eslint/recommended', + 'plugin:jest/recommended', ], diff --git a/docs/getting-started/linting/TYPED_LINTING.md b/docs/getting-started/linting/TYPED_LINTING.md index fd6fe4fb2f4..188a7e71ed1 100644 --- a/docs/getting-started/linting/TYPED_LINTING.md +++ b/docs/getting-started/linting/TYPED_LINTING.md @@ -17,7 +17,6 @@ How can we tap into this? There are two small changes you need to make to your c plugins: ['@typescript-eslint'], extends: [ 'eslint:recommended', - 'plugin:@typescript-eslint/eslint-recommended', 'plugin:@typescript-eslint/recommended', + 'plugin:@typescript-eslint/recommended-requiring-type-checking', ], diff --git a/packages/eslint-plugin/docs/rules/explicit-module-boundary-types.md b/packages/eslint-plugin/docs/rules/explicit-module-boundary-types.md index 453ec03a12a..b91036ec643 100644 --- a/packages/eslint-plugin/docs/rules/explicit-module-boundary-types.md +++ b/packages/eslint-plugin/docs/rules/explicit-module-boundary-types.md @@ -26,6 +26,7 @@ export var arrowFn = () => 'test'; // All arguments should be typed export var arrowFn = (arg): string => `test ${arg}`; +export var arrowFn = (arg: any): string => `test ${arg}`; export class Test { // Should indicate that no value is returned (void) @@ -51,6 +52,10 @@ export var fn = function (): number { // A return value of type string export var arrowFn = (arg: string): string => `test ${arg}`; +// All arguments should be typed +export var arrowFn = (arg: string): string => `test ${arg}`; +export var arrowFn = (arg: unknown): string => `test ${arg}`; + // Class is not exported class Test { method() { diff --git a/packages/eslint-plugin/docs/rules/naming-convention.md b/packages/eslint-plugin/docs/rules/naming-convention.md index e27aa6e3d2f..90a86eeb56d 100644 --- a/packages/eslint-plugin/docs/rules/naming-convention.md +++ b/packages/eslint-plugin/docs/rules/naming-convention.md @@ -320,10 +320,30 @@ Group Selectors are provided for convenience, and essentially bundle up sets of } ``` +### Enforce that interface names do not begin with an `I` + +```json +{ + "@typescript-eslint/naming-convention": [ + "error", + { + "selector": "interface", + "format": ["PascalCase"], + "prefix": ["T"], + "custom": { + "regex": "^I[A-Z]", + "match": false + } + } + ] +} +``` + ### Enforce the codebase follows ESLint's `camelcase` conventions ```json { + "camelcase": "off", "@typescript-eslint/naming-convention": [ "error", { diff --git a/packages/eslint-plugin/src/configs/README.md b/packages/eslint-plugin/src/configs/README.md index 5105a31eeff..3f232c7d9df 100644 --- a/packages/eslint-plugin/src/configs/README.md +++ b/packages/eslint-plugin/src/configs/README.md @@ -6,6 +6,8 @@ These configs exist for your convenience. They contain configuration intended to The `eslint-recommended` ruleset is meant to be used after extending `eslint:recommended`. It disables rules that are already checked by the TypeScript compiler and enables rules that promote using the more modern constructs TypeScript allows for. +This config is automatically included if you use either the `recommended` or `recommended-requiring-type-checking` configs. + ```cjson { "extends": [ @@ -15,9 +17,11 @@ The `eslint-recommended` ruleset is meant to be used after extending `eslint:rec } ``` +We will not add new rules to the `eslint-recommended` set unless we release a major package version (i.e. it is seen as a breaking change). + ## `recommended` -The recommended set is an **_opinionated_** set of rules that we think you should use because: +The `recommended` set is an **_opinionated_** set of rules that we think you should use because: 1. They help you adhere to TypeScript best practices. 2. They help catch probable issue vectors in your code. @@ -30,9 +34,9 @@ That being said, it is not the only way to use `@typescript-eslint/eslint-plugin - The style used by many OSS TypeScript projects. 2. The combined state of community contributed rulesets at the time of creation. -We will not add new rules to the recommended set unless we release a major package version (i.e. it is seen as a breaking change). +We will not add new rules to the `recommended` set unless we release a major package version (i.e. it is seen as a breaking change). -### Altering the recommended set to suit your project +### Altering the `recommended` set to suit your project If you disagree with a rule (or it disagrees with your codebase), consider using your local config to change the rule config so it works for your project. @@ -46,7 +50,20 @@ If you disagree with a rule (or it disagrees with your codebase), consider using } ``` -### Suggesting changes to the recommended set +### Suggesting changes to the `recommended` set If you feel _very_, **very**, ***very*** strongly that a specific rule should (or should not) be in the recommended ruleset, please feel free to file an issue along with a **detailed** argument explaining your reasoning. We expect to see you citing concrete evidence supporting why (or why not) a rule is considered best practice. **Please note that if your reasoning is along the lines of "it's what my project/company does", or "I don't like the rule", then we will likely close the request without discussion.** + +## `recommended-requiring-type-checking` + +Similar to `recommended`, the `recommended-requiring-type-checking` set is an **_opinionated_** set of rules. The difference being that all rules in this set will require type information to use. + +We will not add new rules to the `recommended-requiring-type-checking` set unless we release a major package version (i.e. it is seen as a breaking change). + +## `all` + +The `all` set simply contains every single rule in this plugin, turn on with its default configuration. +There may be some conflicts between the rules as defaults do not quite align - please file an issue if you encounter any of these. + +This set is considered unstable, as any new rules will be added with only a minor package version bump.