From 9df9fee0b4a23e2ae21e49b25c3c2f3fdafe5c32 Mon Sep 17 00:00:00 2001
From: Josh Goldberg <git@joshuakgoldberg.com>
Date: Thu, 22 Aug 2024 18:52:22 -0400
Subject: [PATCH 1/3] docs: add global variable rule disabling FAQ for ESLint

---
 docs/troubleshooting/faqs/ESLint.mdx | 45 ++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/docs/troubleshooting/faqs/ESLint.mdx b/docs/troubleshooting/faqs/ESLint.mdx
index 5766af8b487a..d1a5cdf0d809 100644
--- a/docs/troubleshooting/faqs/ESLint.mdx
+++ b/docs/troubleshooting/faqs/ESLint.mdx
@@ -84,6 +84,51 @@ module.exports = {
 
 If you choose to leave on the ESLint `no-undef` lint rule, you can [manually define the set of allowed `globals` in your ESLint config](https://eslint.org/docs/user-guide/configuring/language-options#specifying-globals), and/or you can use one of the [pre-defined environment (`env`) configurations](https://eslint.org/docs/user-guide/configuring/language-options#specifying-environments).
 
+## I get errors from the `@typescript-eslint/no-namespace` and/or `no-var` rules about declaring global variables
+
+Two common solutions in TypeScript for declaring the existence of a global variable include:
+
+- `declare global` with a `var`, which violates [`no-var`](https://eslint.org/docs/latest/rules/no-var):
+
+  ```ts
+  declare global {
+    var myValue: string;
+    // Unexpected var, use let or const instead. eslint (no-var)
+  }
+
+  myValue;
+  ```
+
+- `declare namespace globalThis`, which violates [`@typescript-eslint/no-namespace`](https://typescript-eslint.io/rules/no-namespace):
+
+  ```ts
+  declare namespace globalThis {
+    // ES2015 module syntax is preferred over namespaces. eslint (@typescript-eslint/no-namespace)
+    let myValue: string;
+  }
+
+  globalThis.myValue;
+  ```
+
+[Using global variables is generally discouraged](https://stackoverflow.com/questions/10525582/why-are-global-variables-considered-bad-practice).
+If possible, it's best to avoid declaring globals altogether.
+
+If you absolutely must use one of the two strategies, then you can use an [ESLint configuration comment](https://eslint.org/docs/latest/use/configure/rules#using-configuration-comments-1) to disable rules as needed.
+For example:
+
+```ts
+declare global {
+  // eslint-disable-next-line no-var -- Provided by an old third-party integration.
+  var myValue: string;
+}
+```
+
+:::tip
+Whenever you need to disable an ESLint rule, it's best to include an informative comment explaining why.
+:::
+
+See [#9582](https://github.com/typescript-eslint/typescript-eslint/issues/9582 'typescript-eslint/typescript-eslint#9582 Docs: globalThis without ignores of no-var and no-namespace') and [#7941](https://github.com/typescript-eslint/typescript-eslint/issues/7941 'typescript-eslint/typescript-eslint#7941 Base rule extension: no-var configuration for declarations') for discussions around typescript-eslint supporting these use cases.
+
 ## Can I use ESLint's `--cache` with typescript-eslint?
 
 [ESLint's `--cache` option](https://eslint.org/docs/latest/use/command-line-interface#caching) caches on a per-file basis.

From 071c1b21acccc0a2c5b1fd906e3f556d43f851a5 Mon Sep 17 00:00:00 2001
From: Josh Goldberg <git@joshuakgoldberg.com>
Date: Sun, 25 Aug 2024 11:54:54 -0400
Subject: [PATCH 2/3] Linked to FAQ too, good idea

---
 packages/eslint-plugin/docs/rules/no-namespace.mdx | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/eslint-plugin/docs/rules/no-namespace.mdx b/packages/eslint-plugin/docs/rules/no-namespace.mdx
index 3d4f14fe9151..3eefe15fbf5c 100644
--- a/packages/eslint-plugin/docs/rules/no-namespace.mdx
+++ b/packages/eslint-plugin/docs/rules/no-namespace.mdx
@@ -137,6 +137,7 @@ You might consider using [ESLint disable comments](https://eslint.org/docs/lates
 
 ## Further Reading
 
+- [FAQ: I get errors from the `@typescript-eslint/no-namespace` and/or `no-var` rules about declaring global variables](/troubleshooting/faqs/eslint#i-get-errors-from-the-typescript-eslintno-namespace-andor-no-var-rules-about-declaring-global-variables)
 - [Modules](https://www.typescriptlang.org/docs/handbook/modules.html)
 - [Namespaces](https://www.typescriptlang.org/docs/handbook/namespaces.html)
 - [Namespaces and Modules](https://www.typescriptlang.org/docs/handbook/namespaces-and-modules.html)

From 69dc455a01996c7a4df054fd71a9168f9f1fac16 Mon Sep 17 00:00:00 2001
From: Josh Goldberg <git@joshuakgoldberg.com>
Date: Sun, 25 Aug 2024 12:25:39 -0400
Subject: [PATCH 3/3] disable-next-line

---
 packages/eslint-plugin/docs/rules/no-namespace.mdx | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/packages/eslint-plugin/docs/rules/no-namespace.mdx b/packages/eslint-plugin/docs/rules/no-namespace.mdx
index 3eefe15fbf5c..3bb12bf375ae 100644
--- a/packages/eslint-plugin/docs/rules/no-namespace.mdx
+++ b/packages/eslint-plugin/docs/rules/no-namespace.mdx
@@ -137,6 +137,8 @@ You might consider using [ESLint disable comments](https://eslint.org/docs/lates
 
 ## Further Reading
 
+{/* cspell:disable-next-line */}
+
 - [FAQ: I get errors from the `@typescript-eslint/no-namespace` and/or `no-var` rules about declaring global variables](/troubleshooting/faqs/eslint#i-get-errors-from-the-typescript-eslintno-namespace-andor-no-var-rules-about-declaring-global-variables)
 - [Modules](https://www.typescriptlang.org/docs/handbook/modules.html)
 - [Namespaces](https://www.typescriptlang.org/docs/handbook/namespaces.html)