docs: Explain what frozen rules mean (#19382)

nzakas · web-flow · commit 758c66bc8d83 · 2025-01-31T14:32:22.000+01:00
* docs: Explain what frozen rules mean fixes #19346 * Update README * Add note about modifying core ruels
diff --git a/README.md b/README.md
@@ -35,7 +35,6 @@ ESLint is a tool for identifying and reporting on patterns found in ECMAScript/J
 1. [Releases](#releases)
 1. [Security Policy](#security-policy)
 1. [Semantic Versioning Policy](#semantic-versioning-policy)
-1. [Stylistic Rule Updates](#stylistic-rule-updates)
 1. [License](#license)
 1. [Team](#team)
 1. [Sponsors](#sponsors)
@@ -191,15 +190,6 @@ ESLint follows [semantic versioning](https://semver.org). However, due to the na
 
 According to our policy, any minor update may report more linting errors than the previous release (ex: from a bug fix). As such, we recommend using the tilde (`~`) in `package.json` e.g. `"eslint": "~3.1.0"` to guarantee the results of your builds.
 
-## Stylistic Rule Updates
-
-Stylistic rules are frozen according to [our policy](https://eslint.org/blog/2020/05/changes-to-rules-policies) on how we evaluate new rules and rule changes.
-This means:
-
-* **Bug fixes**: We will still fix bugs in stylistic rules.
-* **New ECMAScript features**: We will also make sure stylistic rules are compatible with new ECMAScript features.
-* **New options**: We will **not** add any new options to stylistic rules unless an option is the only way to fix a bug or support a newly-added ECMAScript feature.
-
 ## License
 
 MIT License
diff --git a/docs/src/_includes/components/rule-categories.macro.html b/docs/src/_includes/components/rule-categories.macro.html
@@ -32,7 +32,7 @@
     <div class="rule-category">
         <span class="rule-category__icon">❄️ <span class="visually-hidden">Frozen</span></span>
         <p class="rule-category__description">
-            This rule is currently frozen and is not accepting feature requests.
+            This rule is currently <a href="../contribute/core-rules#frozen-rules">frozen</a> and is not accepting feature requests.
         </p>
     </div>
     {%- endif -%}
diff --git a/docs/src/contribute/core-rules.md b/docs/src/contribute/core-rules.md
@@ -108,3 +108,15 @@ The rule naming conventions for ESLint are as follows:
 * Use dashes between words.
 * If your rule only disallows something, prefix it with `no-` such as `no-eval` for disallowing `eval()` and `no-debugger` for disallowing `debugger`.
 * If your rule is enforcing the inclusion of something, use a short name without a special prefix.
+
+## Frozen Rules
+
+When rules are feature complete, they are marked as frozen (indicated with ❄️ in the documentation). Rules are considered feature complete when the intended purpose of the rule has been fully implemented such that it catches 80% or more of expected violations and covers the majority of common exceptions. After that point, we expect users to use [disable comments](../use/configure/rules#using-configuration-comments-1) when they find an edge case that isn't covered.
+
+When a rule is frozen, it means:
+
+* **Bug fixes**: We will still fix confirmed bugs.
+* **New ECMAScript features**: We will ensure compatibility with new ECMAScript features, meaning the rule will not break on new syntax.
+* **New options**: We will **not** add any new options unless an option is the only way to fix a bug or support a newly-added ECMAScript feature.
+
+If you find that a frozen rule would work better for you with a change, we recommend copying the rule source code and modifying it to fit your needs.
