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’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Deprecate stylistic rules handled by Prettier #6504
Changes from all commits
81a02b7
6f516b5
e1fe14a
2be55ee
bdcf94e
d9ff205
0732ce9
0b37311
9f04234
09e5a50
23a4e75
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,5 @@ | ||
--- | ||
"stylelint": minor | ||
--- | ||
|
||
Deprecated: stylistic rules handled by Prettier |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,12 +1,65 @@ | ||
# Migrating to 15.0.0 | ||
|
||
## Remove support for processors | ||
This release contains significant and breaking changes that will help us modernize our code so that Stylelint remains free of security issues. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. [Note] Provide some context to changes. Doesn't go into the details of:
|
||
|
||
We removed the support for processors. Instead, please use [custom syntaxes](../developer-guide/syntaxes.md). | ||
## Significant change | ||
|
||
## Change of `overrides.extends` behavior | ||
We deprecated [most of the rules that enforce stylistic conventions](../user-guide/rules.md#deprecated). You should remove these rules from your configuration object. | ||
|
||
We changed the `overrides.extends` behavior to merge rather than replace, to make it consistent with the `overrides.plugins`. | ||
We recommend: | ||
|
||
- using a pretty printer, like [Prettier](https://prettier.io/), alongside Stylelint | ||
- extending [our standard config](https://www.npmjs.com/package/stylelint-config-standard) in your configuration object | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. [Note] Opportunity to suggest our users adopt our standard config, if they haven't already. |
||
|
||
Stylelint and pretty printers are complementary tools that work together to help you write consistent and error-free code. To help facilitate this, we've removed the [deprecated rules](../user-guide/rules.md#deprecated) from the latest version of [our standard config](https://www.npmjs.com/package/stylelint-config-standard). You can [extend](../user-guide/configure.md#extends) the config using: | ||
|
||
```diff json | ||
{ | ||
+ "extends": ["stylelint-config-standard"], | ||
"rules" { .. } | ||
} | ||
``` | ||
|
||
[Our standard config](https://www.npmjs.com/package/stylelint-config-standard) turns on many of the [other rules that enforce conventions](../user-guide/rules.md#enforce-conventions), e.g. most of the [`*-notation`](../user-guide/rules.md#notation), [`*-pattern`](../user-guide/rules.md#pattern) and [`*-quotes`](../user-guide/rules.md#quotes) rules. We recommend adding more of [the rules that enforce conventions](../user-guide/rules.md#enforce-conventions) to your config as many of them will be specific to your needs, e.g. what [units you allow](../../lib/rules/unit-allowed-list/README.md) in your code. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. [Note] We originally positioned our standard config to be about formatting whitespace. It's changed significantly over time, especially now that we're deprecating the stylistic rules. This bit communicates that our standard config still offers plenty of value over our recommended config as it turns on a lot of rules that enforce conventions. Additionally, we recently regrouped how we list rules and this draws attention to that. All this is to inform our users that Stylelint is the best (and perhaps only) tool for enforcing non-stylistic conventions. I suggest we mark the rules in our list that are included in our configs. This will help our users make use of the convention enforcing rules. Our current approach of listing rules in the config README isn't great as:
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Sounds good. Do you already have an idea of how to realize it? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
I figured we could just whack an "R" and/or "S" on the end of the rule description and throw a key at the top. Something along the lines of: (R & S) = In our recommended and standard configs
What do you think? (We can do it in a follow-up pull request.) There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I see. It's the simplest solution, but there is a way to use emojis and a table for more readability. This is an example of In addition, if we could add such information as There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Ⓡ and Ⓢ |
||
|
||
For example, you can: | ||
|
||
- [allow, disallow and require many things](../user-guide/rules.md#allowed-disallowed--required) | ||
- [set limits on things like selectors](../user-guide/rules.md#max--min) | ||
|
||
Additionally, you may no longer need to extend [Prettier's Stylelint config](https://www.npmjs.com/package/stylelint-config-prettier) as there should be no conflicting rules: | ||
|
||
```diff json | ||
{ | ||
- "extends": ["stylelint-config-prettier"], | ||
"rules" { .. } | ||
} | ||
``` | ||
|
||
If you want to continue using Stylelint to enforce stylistic consistency, you can [migrate the deprecated rules you need to a plugin](../developer-guide/plugins.md). We will remove the rules from Stylelint in the next major release. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. [Note] This is at the bottom as it's not the recommended route. The rules are problematic and a plugin would suffer the same issues:
Pretty printing an AST based on the line length is a better approach. |
||
|
||
## Breaking changes | ||
|
||
Three breaking changes may also affect you: | ||
|
||
- removed support for Node.js 12 | ||
- removed support for processors | ||
- changed `overrides.extends` behavior | ||
|
||
## Removed support for Node.js 12 | ||
|
||
You should use the following or higher versions of Node.js: | ||
|
||
- 14.13.1 | ||
- 16.0.0 | ||
|
||
### Removed support for processors | ||
|
||
You should use a [custom syntax](../developer-guide/syntaxes.md)](../developer-guide/syntaxes.md) instead. | ||
|
||
### Changed `overrides.extends` behavior | ||
|
||
To be consistent with the `overrides.plugins`, `overrides.extends` will merge rather than replace. | ||
|
||
If you would like to keep the previous behavior, you should change your config to: | ||
|
||
|
@@ -25,10 +78,3 @@ If you would like to keep the previous behavior, you should change your config t | |
] | ||
} | ||
``` | ||
|
||
## Node.js 12 | ||
|
||
Support for Node.js 12 was dropped. You should use the following or higher versions of Node.js: | ||
|
||
- 14.13.1 | ||
- 16.0.0 |
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -29,18 +29,6 @@ npx stylelint "**/*.css" | |
|
||
_You should include quotation marks around file globs._ | ||
|
||
If you use a pretty printer alongside Stylelint, you should turn off any conflicting rules. For example, you can use [Prettier's shared config](https://www.npmjs.com/package/stylelint-config-prettier) to do that: | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. [Note] We don't need to suggest using the config anymore as the configs won't conflict. |
||
|
||
```shell | ||
npm install --save-dev stylelint-config-prettier | ||
``` | ||
|
||
```json | ||
{ | ||
"extends": ["stylelint-config-standard", "stylelint-config-prettier"] | ||
} | ||
``` | ||
|
||
## Linting everything else | ||
|
||
You'll need to use a [custom syntax](usage/options.md#customsyntax) written by the community. | ||
|
@@ -152,7 +140,7 @@ You can adapt your: | |
- [rules](configure.md#rules) | ||
- [plugins](configure.md#plugins) | ||
|
||
We recommend you add [more of the rules that enforce conventions](rules.md#enforce-non-stylistic-conventions) to your configuration, e.g. [`unit-allowed-list`](../../lib/rules/unit-allowed-list/README.md) and [`selector-max-id`](../../lib/rules/selector-max-id/README.md). These are powerful rules that you can use to enforce non-stylistic consistency in your code. | ||
We recommend you add [more of the rules that enforce conventions](rules.md#enforce-conventions) to your configuration, e.g. [`unit-allowed-list`](../../lib/rules/unit-allowed-list/README.md) and [`selector-max-id`](../../lib/rules/selector-max-id/README.md). These are powerful rules that you can use to enforce non-stylistic consistency in your code. | ||
|
||
You can add plugins written by the community to lint more things. For example, you may want to use the [stylelint-csstree-validator plugin](https://www.npmjs.com/package/stylelint-csstree-validator) to validate property and value pairs. | ||
|
||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[Note] Pulled this out so that the list of rules is near the top of the page.