Deprecate stylistic rules handled by Prettier

.changeset/red-coins-rescue.md

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

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/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

@@ -152,7 +152,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.
 

docs/user-guide/rules.md

@@ -3,8 +3,8 @@
 There are over 170 rules that help you:
 
 - [avoid errors](#avoid-errors)
-- [enforce non-stylistic conventions](#enforce-non-stylistic-conventions)
-- [enforce stylistic conventions](#enforce-stylistic-conventions) (frozen)
+- [enforce conventions](#enforce-conventions)
+- [deprecated](#deprecated)
 
 The rules:
 
@@ -101,7 +101,7 @@ Disallow unknown things with these `no-unknown` rules.
 - [`selector-type-no-unknown`](../../lib/rules/selector-type-no-unknown/README.md): Disallow unknown type selectors.
 - [`unit-no-unknown`](../../lib/rules/unit-no-unknown/README.md): Disallow unknown units.
 
-## Enforce non-stylistic conventions
+## Enforce conventions
 
 You can enforce non-stylistic conventions with these `no` and `list` rules. They are powerful rules for making your CSS consistent. You'll need to configure most of them to suit your needs.
 
@@ -187,6 +187,21 @@ Allow, disallow or require things with these `allowed-list`, `disallowed-list`,
 
 - [`value-no-vendor-prefix`](../../lib/rules/value-no-vendor-prefix/README.md): Disallow vendor prefixes for values (Autofixable).
 
+### Case
+
+Specify lowercase or uppercase for words.
+
+- [`function-name-case`](../../lib/rules/function-name-case/README.md): Specify lowercase or uppercase for function names (Autofixable).
+- [`selector-type-case`](../../lib/rules/selector-type-case/README.md): Specify lowercase or uppercase for type selectors (Autofixable).
+- [`value-keyword-case`](../../lib/rules/value-keyword-case/README.md): Specify lowercase or uppercase for keywords values (Autofixable).
+
+### Empty lines
+
+- [`at-rule-empty-line-before`](../../lib/rules/at-rule-empty-line-before/README.md): Require or disallow an empty line before at-rules (Autofixable).
+- [`comment-empty-line-before`](../../lib/rules/comment-empty-line-before/README.md): Require or disallow an empty line before comments (Autofixable).
+- [`custom-property-empty-line-before`](../../lib/rules/custom-property-empty-line-before/README.md): Require or disallow an empty line before custom properties (Autofixable).
+- [`rule-empty-line-before`](../../lib/rules/rule-empty-line-before/README.md): Require or disallow an empty line before rules (Autofixable).
+
 ### Max & min
 
 Apply limits with these `max` and `min` rules.
@@ -248,9 +263,15 @@ Disallow redundancy with these `no-redundant` rules.
 - [`declaration-block-no-redundant-longhand-properties`](../../lib/rules/declaration-block-no-redundant-longhand-properties/README.md): Disallow redundant longhand properties within declaration-block.
 - [`shorthand-property-no-redundant-values`](../../lib/rules/shorthand-property-no-redundant-values/README.md): Disallow redundant values within shorthand properties (Autofixable).
 
-## Enforce stylistic conventions
+### Whitespace inside
+
+Require or disallow whitespace on the inside.
 
-We have frozen these rules — we won't fix bugs nor add options, and we will deprecate then remove them in future releases. We recommend you use a pretty printer (like Prettier) alongside Stylelint rather than these rules. If you prefer to use Stylelint to enforce stylistic consistency, you can [migrate the rules you need to a plugin](../developer-guide/plugins.md).
+- [`comment-whitespace-inside`](../../lib/rules/comment-whitespace-inside/README.md): Require or disallow whitespace on the inside of comment markers (Autofixable).
+
+## Deprecated
+
+We have deprecated these rules — we won't fix bugs nor add options, and we will remove them in future releases. We recommend you use a pretty printer (like Prettier) alongside Stylelint rather than these rules. If you prefer to use Stylelint to enforce stylistic consistency, you can [migrate the rules you need to a plugin](../developer-guide/plugins.md).
 
 The whitespace rules allow you to enforce an empty line, a single space, a newline or no space in some specific part of the stylesheet.
 
@@ -299,44 +320,11 @@ a { transform: translate( 1, 1 ); }
  * The space inside these two parentheses */
 ```
 
-### Not handled by pretty printers
-
-#### Value
-
-- [`value-keyword-case`](../../lib/rules/value-keyword-case/README.md): Specify lowercase or uppercase for keywords values (Autofixable).
-
-#### Function
-
-- [`function-name-case`](../../lib/rules/function-name-case/README.md): Specify lowercase or uppercase for function names (Autofixable).
-
-#### Custom property
-
-- [`custom-property-empty-line-before`](../../lib/rules/custom-property-empty-line-before/README.md): Require or disallow an empty line before custom properties (Autofixable).
-
-#### Selector
-
-- [`selector-type-case`](../../lib/rules/selector-type-case/README.md): Specify lowercase or uppercase for type selectors (Autofixable).
-
-#### Rule
-
-- [`rule-empty-line-before`](../../lib/rules/rule-empty-line-before/README.md): Require or disallow an empty line before rules (Autofixable).
-
-#### At-rule
-
-- [`at-rule-empty-line-before`](../../lib/rules/at-rule-empty-line-before/README.md): Require or disallow an empty line before at-rules (Autofixable).
-
-#### Comment
-
-- [`comment-empty-line-before`](../../lib/rules/comment-empty-line-before/README.md): Require or disallow an empty line before comments (Autofixable).
-- [`comment-whitespace-inside`](../../lib/rules/comment-whitespace-inside/README.md): Require or disallow whitespace on the inside of comment markers (Autofixable).
-
-### Handled by pretty printers
-
-#### Color
+### Color
 
 - [`color-hex-case`](../../lib/rules/color-hex-case/README.md): Specify lowercase or uppercase for hex colors (Autofixable).
 
-#### Function
+### Function
 
 - [`function-comma-newline-after`](../../lib/rules/function-comma-newline-after/README.md): Require a newline or disallow whitespace after the commas of functions (Autofixable).
 - [`function-comma-newline-before`](../../lib/rules/function-comma-newline-before/README.md): Require a newline or disallow whitespace before the commas of functions (Autofixable).
@@ -347,32 +335,32 @@ a { transform: translate( 1, 1 ); }
 - [`function-parentheses-space-inside`](../../lib/rules/function-parentheses-space-inside/README.md): Require a single space or disallow whitespace on the inside of the parentheses of functions (Autofixable).
 - [`function-whitespace-after`](../../lib/rules/function-whitespace-after/README.md): Require or disallow whitespace after functions (Autofixable).
 
-#### Number
+### Number
 
 - [`number-leading-zero`](../../lib/rules/number-leading-zero/README.md): Require or disallow a leading zero for fractional numbers less than 1 (Autofixable).
 - [`number-no-trailing-zeros`](../../lib/rules/number-no-trailing-zeros/README.md): Disallow trailing zeros in numbers (Autofixable).
 
-#### String
+### String
 
 - [`string-quotes`](../../lib/rules/string-quotes/README.md): Specify single or double quotes around strings (Autofixable).
 
-#### Unit
+### Unit
 
 - [`unit-case`](../../lib/rules/unit-case/README.md): Specify lowercase or uppercase for units (Autofixable).
 
-#### Value list
+### Value list
 
 - [`value-list-comma-newline-after`](../../lib/rules/value-list-comma-newline-after/README.md): Require a newline or disallow whitespace after the commas of value lists (Autofixable).
 - [`value-list-comma-newline-before`](../../lib/rules/value-list-comma-newline-before/README.md): Require a newline or disallow whitespace before the commas of value lists.
 - [`value-list-comma-space-after`](../../lib/rules/value-list-comma-space-after/README.md): Require a single space or disallow whitespace after the commas of value lists (Autofixable).
 - [`value-list-comma-space-before`](../../lib/rules/value-list-comma-space-before/README.md): Require a single space or disallow whitespace before the commas of value lists (Autofixable).
 - [`value-list-max-empty-lines`](../../lib/rules/value-list-max-empty-lines/README.md): Limit the number of adjacent empty lines within value lists (Autofixable).
 
-#### Property
+### Property
 
 - [`property-case`](../../lib/rules/property-case/README.md): Specify lowercase or uppercase for properties (Autofixable).
 
-#### Declaration
+### Declaration
 
 - [`declaration-bang-space-after`](../../lib/rules/declaration-bang-space-after/README.md): Require a single space or disallow whitespace after the bang of declarations (Autofixable).
 - [`declaration-bang-space-before`](../../lib/rules/declaration-bang-space-before/README.md): Require a single space or disallow whitespace before the bang of declarations (Autofixable).
@@ -381,15 +369,15 @@ a { transform: translate( 1, 1 ); }
 - [`declaration-colon-space-before`](../../lib/rules/declaration-colon-space-before/README.md): Require a single space or disallow whitespace before the colon of declarations (Autofixable).
 - [`declaration-empty-line-before`](../../lib/rules/declaration-empty-line-before/README.md): Require or disallow an empty line before declarations (Autofixable).
 
-#### Declaration block
+### Declaration block
 
 - [`declaration-block-semicolon-newline-after`](../../lib/rules/declaration-block-semicolon-newline-after/README.md): Require a newline or disallow whitespace after the semicolons of declaration blocks (Autofixable).
 - [`declaration-block-semicolon-newline-before`](../../lib/rules/declaration-block-semicolon-newline-before/README.md): Require a newline or disallow whitespace before the semicolons of declaration blocks.
 - [`declaration-block-semicolon-space-after`](../../lib/rules/declaration-block-semicolon-space-after/README.md): Require a single space or disallow whitespace after the semicolons of declaration blocks (Autofixable).
 - [`declaration-block-semicolon-space-before`](../../lib/rules/declaration-block-semicolon-space-before/README.md): Require a single space or disallow whitespace before the semicolons of declaration blocks (Autofixable).
 - [`declaration-block-trailing-semicolon`](../../lib/rules/declaration-block-trailing-semicolon/README.md): Require or disallow a trailing semicolon within declaration blocks (Autofixable).
 
-#### Block
+### Block
 
 - [`block-closing-brace-empty-line-before`](../../lib/rules/block-closing-brace-empty-line-before/README.md): Require or disallow an empty line before the closing brace of blocks (Autofixable).
 - [`block-closing-brace-newline-after`](../../lib/rules/block-closing-brace-newline-after/README.md): Require a newline or disallow whitespace after the closing brace of blocks (Autofixable).
@@ -401,7 +389,7 @@ a { transform: translate( 1, 1 ); }
 - [`block-opening-brace-space-after`](../../lib/rules/block-opening-brace-space-after/README.md): Require a single space or disallow whitespace after the opening brace of blocks (Autofixable).
 - [`block-opening-brace-space-before`](../../lib/rules/block-opening-brace-space-before/README.md): Require a single space or disallow whitespace before the opening brace of blocks (Autofixable).
 
-#### Selector
+### Selector
 
 - [`selector-attribute-brackets-space-inside`](../../lib/rules/selector-attribute-brackets-space-inside/README.md): Require a single space or disallow whitespace on the inside of the brackets within attribute selectors (Autofixable).
 - [`selector-attribute-operator-space-after`](../../lib/rules/selector-attribute-operator-space-after/README.md): Require a single space or disallow whitespace after operators within attribute selectors (Autofixable).
@@ -414,14 +402,14 @@ a { transform: translate( 1, 1 ); }
 - [`selector-pseudo-class-parentheses-space-inside`](../../lib/rules/selector-pseudo-class-parentheses-space-inside/README.md): Require a single space or disallow whitespace on the inside of the parentheses within pseudo-class selectors (Autofixable).
 - [`selector-pseudo-element-case`](../../lib/rules/selector-pseudo-element-case/README.md): Specify lowercase or uppercase for pseudo-element selectors (Autofixable).
 
-#### Selector list
+### Selector list
 
 - [`selector-list-comma-newline-after`](../../lib/rules/selector-list-comma-newline-after/README.md): Require a newline or disallow whitespace after the commas of selector lists (Autofixable).
 - [`selector-list-comma-newline-before`](../../lib/rules/selector-list-comma-newline-before/README.md): Require a newline or disallow whitespace before the commas of selector lists (Autofixable).
 - [`selector-list-comma-space-after`](../../lib/rules/selector-list-comma-space-after/README.md): Require a single space or disallow whitespace after the commas of selector lists (Autofixable).
 - [`selector-list-comma-space-before`](../../lib/rules/selector-list-comma-space-before/README.md): Require a single space or disallow whitespace before the commas of selector lists (Autofixable).
 
-#### Media feature
+### Media feature
 
 - [`media-feature-colon-space-after`](../../lib/rules/media-feature-colon-space-after/README.md): Require a single space or disallow whitespace after the colon in media features (Autofixable).
 - [`media-feature-colon-space-before`](../../lib/rules/media-feature-colon-space-before/README.md): Require a single space or disallow whitespace before the colon in media features (Autofixable).
@@ -430,22 +418,22 @@ a { transform: translate( 1, 1 ); }
 - [`media-feature-range-operator-space-after`](../../lib/rules/media-feature-range-operator-space-after/README.md): Require a single space or disallow whitespace after the range operator in media features (Autofixable).
 - [`media-feature-range-operator-space-before`](../../lib/rules/media-feature-range-operator-space-before/README.md): Require a single space or disallow whitespace before the range operator in media features (Autofixable).
 
-#### Media query list
+### Media query list
 
 - [`media-query-list-comma-newline-after`](../../lib/rules/media-query-list-comma-newline-after/README.md): Require a newline or disallow whitespace after the commas of media query lists (Autofixable).
 - [`media-query-list-comma-newline-before`](../../lib/rules/media-query-list-comma-newline-before/README.md): Require a newline or disallow whitespace before the commas of media query lists.
 - [`media-query-list-comma-space-after`](../../lib/rules/media-query-list-comma-space-after/README.md): Require a single space or disallow whitespace after the commas of media query lists (Autofixable).
 - [`media-query-list-comma-space-before`](../../lib/rules/media-query-list-comma-space-before/README.md): Require a single space or disallow whitespace before the commas of media query lists (Autofixable).
 
-#### At-rule
+### At-rule
 
 - [`at-rule-name-case`](../../lib/rules/at-rule-name-case/README.md): Specify lowercase or uppercase for at-rules names (Autofixable).
 - [`at-rule-name-newline-after`](../../lib/rules/at-rule-name-newline-after/README.md): Require a newline after at-rule names.
 - [`at-rule-name-space-after`](../../lib/rules/at-rule-name-space-after/README.md): Require a single space after at-rule names (Autofixable).
 - [`at-rule-semicolon-newline-after`](../../lib/rules/at-rule-semicolon-newline-after/README.md): Require a newline after the semicolon of at-rules (Autofixable).
 - [`at-rule-semicolon-space-before`](../../lib/rules/at-rule-semicolon-space-before/README.md): Require a single space or disallow whitespace before the semicolons of at-rules.
 
-#### General / Sheet
+### General / Sheet
 
 - [`indentation`](../../lib/rules/indentation/README.md): Specify indentation (Autofixable).
 - [`linebreaks`](../../lib/rules/linebreaks/README.md): Specify unix or windows linebreaks (Autofixable).

lib/rules/__tests__/index.test.js

@@ -32,6 +32,16 @@ describe('fixable rules', () => {
 	});
 });
 
+describe('deprecated rules', () => {
+	const deprecatedRules = Object.entries(rules).filter(([, rule]) => rule.meta.deprecated);
+
+	test.each(deprecatedRules)('"%s" should describe deprecation in the doc', async (name) => {
+		const doc = await fs.promises.readFile(path.join(__dirname, '..', name, 'README.md'), 'utf8');
+
+		expect(doc).toMatch('> **Warning**');
+	});
+});
+
 describe('custom message option', () => {
 	test.each(Object.keys(rules))(
 		'"%s" should describe a custom message option in the doc',

lib/rules/at-rule-name-case/README.md

@@ -1,5 +1,7 @@
 # at-rule-name-case
 
+> **Warning** This rule is deprecated and will be removed in the future.
+
 Specify lowercase or uppercase for at-rules names.
 
 <!-- prettier-ignore -->

lib/rules/at-rule-name-case/index.js

@@ -14,6 +14,7 @@ const messages = ruleMessages(ruleName, {
 const meta = {
 	url: 'https://stylelint.io/user-guide/rules/at-rule-name-case',
 	fixable: true,
+	deprecated: true,
 };
 
 /** @type {import('stylelint').Rule} */

lib/rules/at-rule-name-newline-after/README.md

@@ -1,5 +1,7 @@
 # at-rule-name-newline-after
 
+> **Warning** This rule is deprecated and will be removed in the future.
+
 Require a newline after at-rule names.
 
 <!-- prettier-ignore -->

lib/rules/at-rule-name-newline-after/index.js

@@ -13,6 +13,7 @@ const messages = ruleMessages(ruleName, {
 
 const meta = {
 	url: 'https://stylelint.io/user-guide/rules/at-rule-name-newline-after',
+	deprecated: true,
 };
 
 /** @type {import('stylelint').Rule} */

lib/rules/at-rule-name-space-after/README.md

@@ -1,5 +1,7 @@
 # at-rule-name-space-after
 
+> **Warning** This rule is deprecated and will be removed in the future.
+
 Require a single space after at-rule names.
 
 <!-- prettier-ignore -->

lib/rules/at-rule-name-space-after/index.js

@@ -14,6 +14,7 @@ const messages = ruleMessages(ruleName, {
 const meta = {
 	url: 'https://stylelint.io/user-guide/rules/at-rule-name-space-after',
 	fixable: true,
+	deprecated: true,
 };
 
 /** @type {import('stylelint').Rule} */

lib/rules/at-rule-semicolon-newline-after/README.md

@@ -1,5 +1,7 @@
 # at-rule-semicolon-newline-after
 
+> **Warning** This rule is deprecated and will be removed in the future.
+
 Require a newline after the semicolon of at-rules.
 
 <!-- prettier-ignore -->

lib/rules/at-rule-semicolon-newline-after/index.js

@@ -18,6 +18,7 @@ const messages = ruleMessages(ruleName, {
 const meta = {
 	url: 'https://stylelint.io/user-guide/rules/at-rule-semicolon-newline-after',
 	fixable: true,
+	deprecated: true,
 };
 
 /** @type {import('stylelint').Rule} */

lib/rules/at-rule-semicolon-space-before/README.md

@@ -1,5 +1,7 @@
 # at-rule-semicolon-space-before
 
+> **Warning** This rule is deprecated and will be removed in the future.
+
 Require a single space or disallow whitespace before the semicolons of at-rules.
 
 <!-- prettier-ignore -->