Docs: Added note about Node/CJS scoping to no-redeclare (fixes #8814) (…

…#8820)

docs/rules/no-redeclare.md

@@ -32,6 +32,8 @@ If set to `true`, this rule also checks redeclaration of built-in globals, such
 
 ### builtinGlobals
 
+The `"builtinGlobals"` option will check for redeclaration of built-in globals in global scope.
+
 Examples of **incorrect** code for the `{ "builtinGlobals": true }` option:
 
 ```js
@@ -50,3 +52,9 @@ var top = 0;
 ```
 
 The `browser` environment has many built-in global variables (for example, `top`). Some of built-in global variables cannot be redeclared.
+
+Note that when using the `node` or `commonjs` environments (or `ecmaFeatures.globalReturn`, if using the default parser), the top scope of a program is not actually the global scope, but rather a "module" scope. When this is the case, declaring a variable named after a builtin global is not a redeclaration, but rather a shadowing of the global variable. In that case, the [`no-shadow`](no-shadow.md) rule with the `"builtinGlobals"` option should be used.
+
+## Related Rules
+
+* [no-shadow](no-shadow.md)