Docs: update rule deprecation policy (fixes #8635) (#9033)

eslint · Aug 1, 2017 · d0f78ec · d0f78ec
1 parent 5ab282f
commit d0f78ec
Show file tree

Hide file tree

Showing 2 changed files with 7 additions and 8 deletions.
diff --git a/conf/category-list.json b/conf/category-list.json
@@ -10,12 +10,12 @@
     ],
     "deprecated": {
         "name": "Deprecated",
-        "description": "These rules have been deprecated and replaced by newer rules:",
+        "description": "These rules have been deprecated in accordance with the [deprecation policy](/docs/user-guide/rule-deprecation), and replaced by newer rules:",
         "rules": []
     },
     "removed": {
         "name": "Removed",
-        "description": "These rules from older versions of ESLint have been replaced by newer rules:",
+        "description": "These rules from older versions of ESLint (before the [deprecation policy](/docs/user-guide/rule-deprecation) existed) have been replaced by newer rules:",
         "rules": [
             { "removed": "generator-star", "replacedBy": ["generator-star-spacing"] },
             { "removed": "global-strict", "replacedBy": ["strict"] },

diff --git a/docs/user-guide/rule-deprecation.md b/docs/user-guide/rule-deprecation.md
@@ -2,13 +2,12 @@
 
 Balancing the trade-offs of improving a tool and the frustration these changes can cause is a difficult task. One key area in which this affects our users is in the removal of rules.
 
-The ESLint team is committed to making upgrading as easy and painless as possible. To that end, the team has agreed upon some guidelines for deprecating rules in the future. The goal of these guidelines is to allow for improvements and changes to be made without breaking existing configurations.
+The ESLint team is committed to making upgrading as easy and painless as possible. To that end, the team has agreed upon the following set of guidelines for deprecating rules in the future. The goal of these guidelines is to allow for improvements and changes to be made without breaking existing configurations.
 
-Until May 1, 2017, the team has committed to not remove any rules in any releases of ESLint; however, the team will deprecate rules as needed. When a rule is deprecated, it means that:
+* Rules will never be removed from ESLint.
+* Rules will be deprecated as needed, and marked as such in all documentation.
+* After a rule has been deprecated, the team will no longer do any work on it. This includes bug fixes, enhancements, and updates to the rule's documentation. Issues and pull requests related to deprecated rule will not be accepted and will be closed.
 
-* The rule will be marked as deprecated in all documentation.
-* The team will no longer do any work on the rule. This includes bug fixes, enhancements, and updates to the rule's documentation. Issues and pull requests related to the deprecated rule will not be accepted and will be closed automatically.
-
-After May 1, 2017, the team will revisit all deprecated rules and evaluate whether they should actually be removed or not. If the rule is removed at this time, users will have to adjust their configuration accordingly.
+Since deprecated rules will never be removed, you can continue to use them indefinitely if they are working for you. However, keep in mind that deprecated rules will effectively be unmaintained.
 
 We hope that by following these guidelines we will be able to continue improving and working to make ESLint the best tool it can be while causing as little disruption to our users as possible during the process.