Document list of rules by what-they-do groups (#6390)

Co-authored-by: Masafumi Koba <473530+ybiquitous@users.noreply.github.com>

CHANGELOG.md

@@ -826,7 +826,7 @@ This release is accompanied by:
 
 - A new [semantic version policy](docs/about/semantic-versioning.md). The use of the tilde (`~`) in `package.json` is now recommended, e.g. `"stylelint": "~8.0.0"`, to guarantee the results of your builds ([#1865](https://github.com/stylelint/stylelint/issues/1865)).
 - A new [VISION document](docs/about/vision.md), complemented by ([#2704](https://github.com/stylelint/stylelint/pull/2704)):
-  - The restructuring of the [list of rules](docs/user-guide/rules/list.md) into three groups:
+  - The restructuring of the [list of rules](docs/user-guide/rules.md) into three groups:
     - Possible errors
     - Limit language features
     - Stylistic issues

CONTRIBUTING.md

@@ -17,10 +17,10 @@ Not only will you help Stylelint thrive, but you may learn a thing or two — ab
 
 ## Code contributions
 
-To start coding, you'll need:
+To start coding, you'll need the:
 
-- a minimum of [Node.js](https://nodejs.org/en/) v10, though we do recommend using the latest LTS release
-- the latest [npm](https://www.npmjs.com/)
+- LTS release of [Node.js](https://nodejs.org/en/)
+- latest [npm](https://www.npmjs.com/)
 
 Then:
 

README.md

@@ -26,19 +26,20 @@ And can be extended to:
 
 ## How it'll help you
 
-It'll help you **avoid errors**, for example styles that are:
+It'll help you **avoid errors**, for example:
 
-- invalid, e.g. malformed hex colors and named grid areas
-- valid but with unintended consequences, e.g. duplicated selectors and overridden properties
+- invalid things, e.g. malformed hex colors and named grid areas
+- 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 conventions**, for example:
+And **enforce non-stylistic 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
 
-There are also rules for enforcing stylistic consistency, but we now recommend you use Stylelint alongside a pretty printer like Prettier. Linters and pretty printers are complementary tools that work together.
+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.
 
 ## Example output
 
@@ -49,21 +50,19 @@ There are also rules for enforcing stylistic consistency, but we now recommend y
 - User guide
   - [Getting started](docs/user-guide/get-started.md)
   - [Configuration](docs/user-guide/configure.md)
-  - Rules
-    - [List of rules](docs/user-guide/rules/list.md)
-    - [About rules](docs/user-guide/rules/about.md)
-    - [Combining rules](docs/user-guide/rules/combine.md)
-    - [Using regex in rules](docs/user-guide/rules/regex.md)
+  - [Rules](docs/user-guide/rules.md)
   - Usage
     - [CLI](docs/user-guide/usage/cli.md)
     - [Node.js API](docs/user-guide/usage/node-api.md)
     - [PostCSS plugin](docs/user-guide/usage/postcss-plugin.md)
-    - [Shared options](docs/user-guide/usage/options.md)
+    - [Options](docs/user-guide/usage/options.md)
   - Integrations
     - [Editor integrations](docs/user-guide/integrations/editor.md)
     - [Task runner integrations](docs/user-guide/integrations/task-runner.md)
     - [Other integrations](docs/user-guide/integrations/other.md)
   - [Ignoring code](docs/user-guide/ignore-code.md)
+  - [Combining rules](docs/user-guide/combine.md)
+  - [Using regex](docs/user-guide/regex.md)
   - [Errors & warnings](docs/user-guide/errors.md)
 - Developer guide
   - [Working on rules](docs/developer-guide/rules.md)
@@ -80,7 +79,6 @@ There are also rules for enforcing stylistic consistency, but we now recommend y
   - [Performing releases](docs/maintainer-guide/releases.md)
 - About
   - [Vision](docs/about/vision.md)
-  - [Linting](docs/about/linting.md)
   - [Semantic versioning](docs/about/semantic-versioning.md)
 
 ## Contributors

SUPPORT.md

@@ -4,8 +4,8 @@ One of our frequently visited documentation sections might answer your query:
 
 - [Turning off rules](docs/user-guide/configure.md#rules)
 - [Ignoring code](docs/user-guide/ignore-code.md)
-- [Using regexes to configure rules](docs/user-guide/rules/regex.md)
-- [Combining rules to enforce your code style](docs/user-guide/rules/combine.md)
+- [Using regexes to configure rules](docs/user-guide/regex.md)
+- [Combining rules to enforce your code style](docs/user-guide/combine.md)
 
 If they don't, then post your query on [Stack Overflow](https://stackoverflow.com/questions/tagged/stylelint).
 

docs/about/vision.md

@@ -1,6 +1,6 @@
 # Vision
 
-A linter for CSS and CSS-like languages that is:
+A linter and validator for CSS that is:
 
 - complete - coverage of all standard CSS syntax
 - extensible - multiple points of extension
@@ -13,8 +13,8 @@ A linter for CSS and CSS-like languages that is:
 
 Provide built-in rules for standard CSS syntax that:
 
-- [avoid errors](../user-guide/rules/list.md#avoid-errors)
-- [enforce conventions](../user-guide/rules/list.md#enforce-conventions)
+- [avoid errors](../user-guide/rules.md#avoid-errors)
+- [enforce non-stylistic conventions](../user-guide/rules.md#enforce-non-stylistic-conventions)
 
 ## Extensible
 
@@ -34,7 +34,7 @@ Provide a robust tool with a [comprehensive test suite](../developer-guide/rules
 
 ## Consistent
 
-Provide consistency throughout, including consistent [rules](../user-guide/rules/about.md).
+Provide consistency throughout, including consistent conventions for our rules and options.
 
 ## Performant
 

docs/developer-guide/formatters.md

@@ -59,7 +59,7 @@ And the second argument (`returnValue`) is an object (type `LinterResult`) with
   },
   "ruleMetadata": {
     "block-no-empty": {
-      "url": "https://stylelint.io/user-guide/rules/list/block-no-empty"
+      "url": "https://stylelint.io/user-guide/rules/block-no-empty"
     },
     // other rules...
   }

docs/developer-guide/plugins.md

@@ -1,6 +1,6 @@
 # Writing plugins
 
-Plugins are rules and sets of rules built by the community.
+Plugins are rules and sets of rules built by the community. They might support a particular methodology or toolset, or apply to non-standard constructs and features, or be for specific use cases.
 
 We recommend your plugin adheres to [Stylelint's conventions](rules.md) for:
 

docs/developer-guide/rules.md

@@ -4,10 +4,7 @@ Please help us create, enhance, and debug our rules!
 
 ## Add a rule
 
-You should:
-
-1. Get yourself ready to [contribute code](../../CONTRIBUTING.md#code-contributions).
-2. Familiarize yourself with the [conventions and patterns](../user-guide/rules/about.md) for rules.
+You should get yourself ready to [contribute code](../../CONTRIBUTING.md#code-contributions).
 
 ### Write the rule
 
@@ -57,8 +54,46 @@ Use the:
 
 ### Add options
 
+Each rule can accept a primary and an optional secondary option.
+
 Only add an option to a rule if it addresses a _requested_ use case to avoid polluting the tool with unused features.
 
+#### Primary
+
+Every rule _must have_ a primary option. For example, in:
+
+- `"font-weight-notation": "numeric"`, the primary option is `"numeric"`
+- `"selector-max-type": [2, { "ignoreTypes": ["custom"] }]`, the primary option is `2`
+
+Rules are named to encourage explicit primary options. For example, `font-weight-notation: "numeric"|"named-where-possible"` rather than `font-weight-numeric: "always"|"never"`. As `font-weight-named: "never"` _implies_ always numeric, whereas `font-weight-notation: "numeric"` makes it _explicit_.
+
+#### Secondary
+
+Some rules require extra flexibility to address edge cases. These can use an optional secondary options object. For example, in:
+
+- `"font-weight-notation": "numeric"` there is no secondary options object
+- `"selector-max-type": [2, { "ignore": ["descendant] }]`, the secondary options object is `{ "ignore": ["descendant] }`
+
+The most typical secondary options are `"ignore": []` and `"except": []`.
+
+##### Keyword `"ignore"` and `"except"`
+
+The `"ignore"` and `"except"` options accept an array of predefined keyword options, e.g. `["relative", "first-nested", "descendant"]`:
+
+- `"ignore"` skips-over a particular pattern
+- `"except"` inverts the primary option for a particular pattern
+
+##### User-defined `"ignore*"`
+
+Some rules accept a _user-defined_ list of things to ignore. This takes the form of `"ignore<Things>": []`, e.g. `"ignoreAtRules": []`.
+
+The `ignore*` options let users ignore non-standard syntax at the _configuration level_. For example, the:
+
+- `:global` and `:local` pseudo-classes introduced in CSS Modules
+- `@debug` and `@extend` at-rules introduced in SCSS
+
+Methodologies and language extensions come and go quickly, and this approach ensures our codebase does not become littered with code for obsolete things.
+
 If your rule can accept an array as its primary option, you must designate this by setting the property `primaryOptionArray = true` on your rule function. For example:
 
 ```js
@@ -75,6 +110,18 @@ module.exports = rule;
 
 There is one caveat here: If your rule accepts a primary option array, it cannot also accept a primary option object. Whenever possible, if you want your rule to accept a primary option array, you should make an array the only possibility, instead of allowing for various data structures.
 
+### Add problem messages
+
+Add problem messages in form of:
+
+- "Expected \[something\] \[in some context\]"
+- "Unexpected \[something\] \[in some context\]"
+
+If the rule has autofix use:
+
+- 'Expected "\[unfixed\]" to be "\[fixed\]"' for short strings
+- 'Expected "\[primary\]" ... notation' for long strings
+
 ### Add autofix
 
 Depending on the rule, it might be possible to automatically fix the rule's problems by mutating the PostCSS AST (Abstract Syntax Tree) using the [PostCSS API](http://api.postcss.org/).
@@ -121,6 +168,7 @@ You should test errors in multiple positions, not the same place every time and
 - the `a` type selector by default
 - the `@media` at-rules by default
 - the `color` property by default
+- the `red` value by default
 - _foo_, _bar_ and _baz_ for names, e.g. `.foo`, `#bar`, `--baz`
 
 #### Commonly overlooked edge-cases
@@ -140,6 +188,24 @@ You should ask yourself how does your rule handle:
 
 ### Write the README
 
+Each rule is accompanied by a README in the following format:
+
+1. Rule name.
+2. Single-line description.
+3. Prototypical code example.
+4. Expanded description (if necessary).
+5. Options.
+6. Example patterns that are considered problems (for each option value).
+7. Example patterns that are _not_ considered problems (for each option value).
+8. Optional options (if applicable).
+
+The single-line description is in the form of:
+
+- "Disallow ..." for `no` rules
+- "Limit ..." for `max` rules
+- "Require ..." for rules that accept `"always"` and `"never"` options
+- "Specify ..." for everything else
+
 You should:
 
 - pick examples from the tests
@@ -166,7 +232,7 @@ Look at the READMEs of other rules to glean more conventional patterns.
 The final step is to add references to the new rule in the following places:
 
 - [The rules `index.js` file](../../lib/rules/index.js)
-- [The list of rules](../user-guide/rules/list.md)
+- [The list of rules](../user-guide/rules.md)
 
 ## Add an option to a rule
 

docs/migration-guide/to-14.md

@@ -40,7 +40,7 @@ Then, update your [configuration object](../user-guide/configure.md) to use it:
 }
 ```
 
-This shared config extends Stylelint to be compatible with SCSS. It configures the [built-in rules](../user-guide/rules/list.md) for SCSS, and includes the [postcss-scss syntax](https://www.npmjs.com/package/postcss-scss) and [stylelint-scss plugin](https://www.npmjs.com/package/stylelint-scss) (a collection of rules specific to SCSS).
+This shared config extends Stylelint to be compatible with SCSS. It configures the [built-in rules](../user-guide/rules.md) for SCSS, and includes the [postcss-scss syntax](https://www.npmjs.com/package/postcss-scss) and [stylelint-scss plugin](https://www.npmjs.com/package/stylelint-scss) (a collection of rules specific to SCSS).
 
 There are other shared configs provided for each language:
 

docs/user-guide/configure.md

@@ -21,7 +21,7 @@ The configuration object has the following properties:
 
 ## `rules`
 
-Rules determine what the linter looks for and complains about. There are [over 170 rules](rules/list.md) built into Stylelint.
+Rules determine what the linter looks for and complains about. There are [over 170 rules](rules.md) built into Stylelint.
 
 _No rules are turned on by default and there are no default values. You must explicitly configure each rule to turn it on._
 
@@ -183,8 +183,8 @@ 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/list.md#avoid-errors)
-- [stylelint-config-standard](https://github.com/stylelint/stylelint-config-standard) - extends recommended one by turning on rules that [enforce conventions](rules/list.md#enforce-conventions)
+- [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)
 
 You'll find more in [awesome stylelint](https://github.com/stylelint/awesome-stylelint#configs).
 
@@ -310,7 +310,7 @@ You can set the default severity level for all rules that do not have a severity
 
 ## `reportDescriptionlessDisables`
 
-Report `stylelint-disable` comments without a description. A [`report*` property](#report-properties) property.
+Report `stylelint-disable` comments without a description. A [`report*`](#report) property.
 
 For example:
 
@@ -324,7 +324,7 @@ For example:
 
 ## `reportInvalidScopeDisables`
 
-Report `stylelint-disable` comments that don't match rules that are specified in the configuration object. A [`report*` property](#report-properties) property.
+Report `stylelint-disable` comments that don't match rules that are specified in the configuration object. A [`report*`](#report) property.
 
 For example:
 
@@ -338,7 +338,7 @@ For example:
 
 ## `reportNeedlessDisables`
 
-Report `stylelint-disable` comments that don't actually match any lints that need to be disabled. A [`report*` property](#report-properties) property.
+Report `stylelint-disable` comments that don't actually match any lints that need to be disabled. A [`report*`](#report) property.
 
 For example:
 
@@ -415,9 +415,9 @@ If your processor has options, make that item an array whose first item is the "
 
 Processors can also only be used with the CLI and the Node.js API, not with the PostCSS plugin. (The PostCSS plugin ignores them.)
 
-## `report*` properties
+## `report*`
 
-These properties provide extra validation for `stylelint-disable` comments. This can be helpful for enforcing useful and well-documented disables.
+These `report*` properties provide extra validation for `stylelint-disable` comments. This can be helpful for enforcing useful and well-documented disables.
 
 The available reports are:
 

docs/user-guide/get-started.md

@@ -67,7 +67,7 @@ npm install --save-dev stylelint stylelint-config-standard-scss
 npx stylelint "**/*.scss"
 ```
 
-This config includes the [postcss-scss syntax](https://www.npmjs.com/package/postcss-scss), configures the [built-in rules](../user-guide/rules/list.md) for SCSS, and includes the [stylelint-scss plugin](https://www.npmjs.com/package/stylelint-scss) (a collection of rules specific to SCSS).
+This config includes the [postcss-scss syntax](https://www.npmjs.com/package/postcss-scss), configures the [built-in rules](../user-guide/rules.md) for SCSS, and includes the [stylelint-scss plugin](https://www.npmjs.com/package/stylelint-scss) (a collection of rules specific to SCSS).
 
 If you use Prettier alongside Stylelint, you should use their [shared config for SCSS](https://www.npmjs.com/package/stylelint-config-prettier-scss):
 
@@ -148,7 +148,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/list.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.
+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.
 
 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/regex.md → docs/user-guide/regex.md

@@ -1,13 +1,11 @@
-# Using regex in rules
+# Using regex
 
-The following classes of rules support regex:
+You can use regex in the `ignore*` secondary options and following classes of rules:
 
 - `*-allowed-list`
 - `*-disallowed-list`
 - `*-pattern`
 
-As does the `ignore*` secondary options.
-
 ## Enforce a case
 
 You can use the regex that corresponds to your chosen case convention: