Deprecate stylistic rules handled by Prettier (#6504)

Co-authored-by: jeddy3 <jeddy3@users.noreply.github.com>

.changeset/red-coins-rescue.md

@@ -0,0 +1,5 @@
+---
+"stylelint": minor
+---
+
+Deprecated: stylistic rules handled by Prettier

README.md

@@ -10,7 +10,7 @@ A mighty, modern linter that helps you avoid errors and enforce conventions in y
 
 It's mighty as it:
 
-- has over **170 built-in rules** for modern CSS syntax and features
+- has over **100 built-in rules** for modern CSS syntax and features
 - supports **plugins** so you can create your own rules
 - automatically **fixes problems** where possible
 - is **well tested** with over 15000 unit tests
@@ -32,14 +32,15 @@ It'll help you **avoid errors**, for example:
 - unknown things, e.g. units and functions that aren't in the CSS specs
 - valid things that are problematic, e.g. duplicated selectors and overridden properties
 
-And **enforce non-stylistic conventions**, for example:
+And **enforce conventions**, for example:
 
 - what units, functions, at-rules etc are allowed
 - consistent patterns for selector names, at-rule names, custom properties etc
 - maximum specificity or maximum quantity of each selector type
 - your preferred notation for color functions, font weight etc
+- consistent empty lines before constructs
 
-There are also rules for enforcing stylistic conventions, but we now recommend you use Stylelint alongside a pretty printer like Prettier. Linters and pretty printers are complementary tools that work together.
+We recommend using Stylelint alongside a pretty printer like Prettier. Linters and pretty printers are complementary tools that work together to help you write consistent and error-free code that is well-formatted.
 
 ## Example output
 

docs/about/vision.md

@@ -14,7 +14,7 @@ A linter and validator for CSS that is:
 Provide built-in rules for standard CSS syntax that:
 
 - [avoid errors](../user-guide/rules.md#avoid-errors)
-- [enforce non-stylistic conventions](../user-guide/rules.md#enforce-non-stylistic-conventions)
+- [enforce conventions](../user-guide/rules.md#enforce-conventions)
 
 ## Extensible
 

docs/developer-guide/rules.md

@@ -6,6 +6,25 @@ Please help us create, enhance, and debug our rules!
 
 You should get yourself ready to [contribute code](../../CONTRIBUTING.md#code-contributions).
 
+### Define the rule
+
+A rule must be:
+
+- for standard CSS syntax only
+- generally useful; not tied to idiosyncratic patterns
+
+And have a:
+
+- clear and unambiguous finished state
+- singular purpose; don't overlap with other rules
+
+It's name is split into two parts:
+
+- the [_thing_](http://apps.workflower.fi/vocabs/css/en) the rule applies to, e.g. `at-rule`
+- what the rule is checking, e.g. `disallowed-list`
+
+Unless it applies to the whole source, then there is no first part.
+
 ### Write the rule
 
 When writing the rule, you should:

docs/migration-guide/to-15.md

@@ -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.
 
-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
+
+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.
+
+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.
+
+## 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

docs/user-guide/configure.md

@@ -184,7 +184,7 @@ You can _extend_ an existing configuration (whether your own or a third-party on
 Popular configurations include:
 
 - [stylelint-config-recommended](https://github.com/stylelint/stylelint-config-recommended) - turns on just the rules that [avoid errors](rules.md#avoid-errors)
-- [stylelint-config-standard](https://github.com/stylelint/stylelint-config-standard) - extends recommended one by turning on rules that [enforce conventions](rules.md#enforce-non-stylistic-conventions)
+- [stylelint-config-standard](https://github.com/stylelint/stylelint-config-standard) - extends recommended one by turning on rules that [enforce conventions](rules.md#enforce-conventions)
 
 You'll find more in [awesome stylelint](https://github.com/stylelint/awesome-stylelint#configs).
 

docs/user-guide/get-started.md

@@ -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:
-
-```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.