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..98486f2bb6c7
--- /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 as a tombstone pointing to the new relevant rule or docs (see [`camelcase`](https://typescript-eslint.io/rules/camelcase/) as an example)
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',
pFad - Phonifier reborn
Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.
Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.
Alternative Proxies:
Alternative Proxy
pFad Proxy
pFad v3 Proxy
pFad v4 Proxy