Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: clarify kinds of lint rules in formatting docs #6510

Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
36 changes: 23 additions & 13 deletions docs/linting/troubleshooting/Formatting.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,17 +6,6 @@ title: What About Formatting?
We strongly recommend against using ESLint for formatting.
We strongly recommend using [Prettier](https://prettier.io), [dprint](https://dprint.dev), or an equivalent instead.

## ESLint Core and Formatting

Per [ESLint's 2020 Changes to Rule Policies blog post](https://eslint.org/blog/2020/05/changes-to-rules-policies#what-are-the-changes):

> Stylistic rules are frozen - we won't be adding any more options to stylistic rules.
> We've learned that there's no way to satisfy everyone's personal preferences, and most of the rules already have a lot of difficult-to-understand options.
> Stylistic rules are those related to spacing, conventions, and generally anything that does not highlight an error or a better way to do something.

We support the ESLint team's decision and backing logic to move away from stylistic rules.
With the exception of bug fixes, no new formatting-related pull requests will be accepted into typescript-eslint.

## Formatters vs. Linters

**Formatters** are tools that verify and correct whitespace issues in code, such as spacing and newlines.
Expand All @@ -40,7 +29,10 @@ Modern formatters such as Prettier are architected in a way that applies formatt

### Suggested Usage - Prettier

We recommend using [`eslint-config-prettier`](https://github.com/prettier/eslint-config-prettier) to disable formatting rules in your ESLint configuration.
Neither typescript-eslint nor ESLint core enable any formatting-related rules in any recommended presets.
However, some third party plugin configurations may still enable that bad practice.

If you see formatting rules enabled in your ESLint configuration, we recommend using [`eslint-config-prettier`](https://github.com/prettier/eslint-config-prettier) to disable formatting rules in your ESLint configuration.
You can then configure your formatter separately from ESLint.

Using this config by adding it to the end of your `extends`:
Expand All @@ -50,6 +42,7 @@ module.exports = {
extends: [
'eslint:recommended',
'plugin:@typescript-eslint/recommended',
'other-configuration-that-enables-formatting-rules',
// Add this line
'prettier',
],
Expand All @@ -59,4 +52,21 @@ module.exports = {
};
```

Note that even if you don't use `prettier`, you can use `eslint-config-prettier` as it exclusively turns **off** all formatting rules.
Note that even if you use a formatter other than `prettier`, you can use `eslint-config-prettier` as it exclusively turns **off** all formatting rules.

## ESLint Core and Formatting

Most lint rules fall into one of two to three categories:

- **Logical**: Rules that care about the logic in runtime behavior of code (such as missing `await`s or invalid logical checks).
- **Stylistic**: Rules that care about style concerns which do impact runtime behavior of code, but generally not logic. These are mostly around naming or which roughly-equivalent syntax constructs to use (such as function declarations vs. arrow functions).
- **Formatting**: Stylistic rules that care only about trivia (semicolons, whitespace, etc.) without impacting the runtime behavior of the code. These rules conflict with dedicated formatters such as Prettier.
JoshuaKGoldberg marked this conversation as resolved.
Show resolved Hide resolved

Per [ESLint's 2020 Changes to Rule Policies blog post](https://eslint.org/blog/2020/05/changes-to-rules-policies#what-are-the-changes), ESLint itself has moved away from _stylistic_ rules, including _formatting_ rules:

> Stylistic rules are frozen - we won't be adding any more options to stylistic rules.
> We've learned that there's no way to satisfy everyone's personal preferences, and most of the rules already have a lot of difficult-to-understand options.
> Stylistic rules are those related to spacing, conventions, and generally anything that does not highlight an error or a better way to do something.

We support the ESLint team's decision and backing logic to move away from _formatting_ and _stylistic_ rules.
With the exception of bug fixes, no new formatting- or stylistic-related pull requests will be accepted into typescript-eslint.