From 501f70becd69816543a0aa625493213f93bdf454 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Fri, 2 Dec 2022 15:38:24 -0500 Subject: [PATCH 1/2] docs: add Rule Deprecations page --- docs/maintenance/ISSUES.md | 1 - docs/maintenance/issues/Rule_Deprecations.md | 34 ++++++++++++++++++++ packages/website/sidebars/sidebar.base.js | 11 ++++++- 3 files changed, 44 insertions(+), 2 deletions(-) create mode 100644 docs/maintenance/issues/Rule_Deprecations.md diff --git a/docs/maintenance/ISSUES.md b/docs/maintenance/ISSUES.md index 3b73d5af1a26..ebddcc6df1b4 100644 --- a/docs/maintenance/ISSUES.md +++ b/docs/maintenance/ISSUES.md @@ -1,6 +1,5 @@ --- id: issues -sidebar_label: Issues title: Issues --- diff --git a/docs/maintenance/issues/Rule_Deprecations.md b/docs/maintenance/issues/Rule_Deprecations.md new file mode 100644 index 000000000000..8f40ca3ec497 --- /dev/null +++ b/docs/maintenance/issues/Rule_Deprecations.md @@ -0,0 +1,34 @@ +--- +id: rule-deprecations +title: Rule Deprecations +--- + +Sometimes a rule that used to be 👍 does not age well and becomes 👎. +In the past, these cases have included: + +- Overly opinionated and/or stylistic rules that don't represent a universal best practice +- Renames +- Rules moved to an external plugin + +In these cases, we aim to remove the old rule with minimal user disruption. + +## Filing the Issue + +Rule deprecations can be filed as a [new issue bypassing templates](https://github.com/typescript-eslint/typescript-eslint/issues/new). + +Provide it an `## Overview` containing: + +- The rule name & link to its documentation page +- A clear explanation of why you believe it should be deprecated +- Whether it exists in popular configs such as `eslint-config-airbnb-typescript` and `eslint-config-standard-with-typescript` +- Sourcegraph queries showing how often it appears in user configs + +> See [#6036](https://github.com/typescript-eslint/typescript-eslint/issues/6036) for examples of those links and queries. + +## Timeline + +1. In any minor/patch version, add [rule `meta` properties](https://eslint.org/docs/latest/developer-guide/working-with-rules#rule-basics): + - `deprecated: true` + - `replacedBy`, if applicable +2. In the next major version, you may delete the rule + - If the rule is relatively popular with users, consider leaving a documentation page pointing to relevant docs diff --git a/packages/website/sidebars/sidebar.base.js b/packages/website/sidebars/sidebar.base.js index 89fa0e543f36..a949c9f2390a 100644 --- a/packages/website/sidebars/sidebar.base.js +++ b/packages/website/sidebars/sidebar.base.js @@ -67,7 +67,16 @@ module.exports = { }, { items: [ - 'maintenance/issues', + { + collapsible: false, + items: ['maintenance/issues/rule-deprecations'], + label: 'Issues', + link: { + id: 'maintenance/issues', + type: 'doc', + }, + type: 'category', + }, 'maintenance/pull-requests', 'maintenance/releases', 'maintenance/versioning', From 3208dd385ba8665bea5dcd44f3e0713a7037cda0 Mon Sep 17 00:00:00 2001 From: Josh Goldberg Date: Wed, 7 Dec 2022 10:13:50 -0500 Subject: [PATCH 2/2] Update docs/maintenance/issues/Rule_Deprecations.md Co-authored-by: Brad Zacher --- docs/maintenance/issues/Rule_Deprecations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/maintenance/issues/Rule_Deprecations.md b/docs/maintenance/issues/Rule_Deprecations.md index 8f40ca3ec497..98486f2bb6c7 100644 --- a/docs/maintenance/issues/Rule_Deprecations.md +++ b/docs/maintenance/issues/Rule_Deprecations.md @@ -31,4 +31,4 @@ Provide it an `## Overview` containing: - `deprecated: true` - `replacedBy`, if applicable 2. In the next major version, you may delete the rule - - If the rule is relatively popular with users, consider leaving a documentation page pointing to relevant docs + - If the rule is relatively popular with users, consider leaving a documentation page as a tombstone pointing to the new relevant rule or docs (see [`camelcase`](https://typescript-eslint.io/rules/camelcase/) as an example)