From e795b779f85a301d191a74d82a8414dd4069d285 Mon Sep 17 00:00:00 2001
From: Josh Goldberg <git@joshuakgoldberg.com>
Date: Sun, 18 Dec 2022 09:42:03 -0500
Subject: [PATCH] docs: added Contributing > Discussions page

---
 .cspell.json                              |  1 +
 docs/contributing/Discussions.md          | 28 +++++++++++++++++++++++
 docs/maintenance/ISSUES.md                |  2 +-
 packages/website/sidebars/sidebar.base.js |  1 +
 4 files changed, 31 insertions(+), 1 deletion(-)
 create mode 100644 docs/contributing/Discussions.md

diff --git a/.cspell.json b/.cspell.json
index f1806362b478..edd2532abf92 100644
--- a/.cspell.json
+++ b/.cspell.json
@@ -62,6 +62,7 @@
     "declarators",
     "destructure",
     "destructured",
+    "discoverability",
     "dprint",
     "errored",
     "erroring",
diff --git a/docs/contributing/Discussions.md b/docs/contributing/Discussions.md
new file mode 100644
index 000000000000..52de99914096
--- /dev/null
+++ b/docs/contributing/Discussions.md
@@ -0,0 +1,28 @@
+---
+id: discussions
+title: Discussions
+---
+
+Most proposals in the typescript-eslint repository happen in [GitHub Issues](https://docs.github.com/issues).
+We generally try to keep conversations inside issues for their discoverability and ability to be linked to [GitHub Pull Requests](https://docs.github.com/pull-requests).
+
+We have [GitHub Discussions](https://docs.github.com/discussions) enabled to enable three kinds of deeper, threaded conversations:
+
+- **Community Feedback**: Questions from the maintainer team that should be raised to the broader community
+- **RFCs (Requests For Comments)**: Formalized proposals for larger changes that should be discussed before turned into issues
+- **Technical Discussions**: Deeper questions about typescript-eslint's architecture and/or APIs
+
+Before filing a Discussion, search the issue tracker for any related conversations.
+Link to them in the Discussion, along with a detailed description of what you'd like to discuss.
+
+:::tip
+For change proposals that match an [existing issue format](https://github.com/typescript-eslint/typescript-eslint/issues/new/choose), keep to filing issues.
+Most don't need to be moved to this separate format.
+We can always move an issue to a discussion if it becomes unexpectedly deep.
+:::
+
+:::caution
+Please don't use Discussions as a support forum.
+We don't have the maintainer-budget to handle that.
+See [Issues > Questions and Support Requests](./Issues.mdx#questions-and-support-requests).
+:::
diff --git a/docs/maintenance/ISSUES.md b/docs/maintenance/ISSUES.md
index ebddcc6df1b4..012ece57fff7 100644
--- a/docs/maintenance/ISSUES.md
+++ b/docs/maintenance/ISSUES.md
@@ -3,7 +3,7 @@ id: issues
 title: Issues
 ---
 
-This document serves as a guide for how you might manage issues, also known as issue triaging.
+This document serves as a guide for how you might manage our [GitHub Issues](https://docs.github.com/issues), also known as issue triaging.
 
 Use your best judgement when triaging issues, and most of all remember to be **kind, friendly, and encouraging** when responding to users.
 Many users are new to open source and/or typed linting.
diff --git a/packages/website/sidebars/sidebar.base.js b/packages/website/sidebars/sidebar.base.js
index fe84b9c1ae39..cd6486355437 100644
--- a/packages/website/sidebars/sidebar.base.js
+++ b/packages/website/sidebars/sidebar.base.js
@@ -38,6 +38,7 @@ module.exports = {
     'custom-rules',
     {
       items: [
+        'contributing/discussions',
         'contributing/issues',
         'contributing/local-development',
         'contributing/pull-requests',