From f8093b65ea88eb11a0d0f4ffdbf7c6f007043238 Mon Sep 17 00:00:00 2001
From: Brent Westbrook <36778786+ntBre@users.noreply.github.com>
Date: Wed, 12 Feb 2025 12:50:13 -0500
Subject: [PATCH] [`flake8-builtins`] Update documentation (`A005`) (#16097)

Follow-up to https://github.com/astral-sh/ruff/pull/15951 to update
* the options links in A005 to reference
`lint.flake8-builtins.builtins-strict-checking`
* the description of the rule to explain strict vs non-strict checking
* the option documentation to point back to the rule
---
 .../flake8_builtins/rules/stdlib_module_shadowing.rs     | 9 +++++++++
 crates/ruff_workspace/src/options.rs                     | 4 ++++
 ruff.schema.json                                         | 2 +-
 3 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/crates/ruff_linter/src/rules/flake8_builtins/rules/stdlib_module_shadowing.rs b/crates/ruff_linter/src/rules/flake8_builtins/rules/stdlib_module_shadowing.rs
index 64bf8691c7..0745d51e4f 100644
--- a/crates/ruff_linter/src/rules/flake8_builtins/rules/stdlib_module_shadowing.rs
+++ b/crates/ruff_linter/src/rules/flake8_builtins/rules/stdlib_module_shadowing.rs
@@ -23,6 +23,14 @@ use crate::settings::LinterSettings;
 /// Standard-library modules can be marked as exceptions to this rule via the
 /// [`lint.flake8-builtins.builtins-allowed-modules`] configuration option.
 ///
+/// By default, only the last component of the module name is considered, so `logging.py`,
+/// `utils/logging.py`, and `utils/logging/__init__.py` would all clash with the builtin `logging`
+/// module. With the [`lint.flake8-builtins.builtins-strict-checking`] option set to `false`, the
+/// module path is considered, so only a top-level `logging.py` or `logging/__init__.py` will
+/// trigger the rule and `utils/logging.py`, for example, would not. In preview mode, the default
+/// value of [`lint.flake8-builtins.builtins-strict-checking`] is `false` rather than `true` in
+/// stable mode.
+///
 /// This rule is not applied to stub files, as the name of a stub module is out
 /// of the control of the author of the stub file. Instead, a stub should aim to
 /// faithfully emulate the runtime module it is stubbing.
@@ -43,6 +51,7 @@ use crate::settings::LinterSettings;
 ///
 /// ## Options
 /// - `lint.flake8-builtins.builtins-allowed-modules`
+/// - `lint.flake8-builtins.builtins-strict-checking`
 #[derive(ViolationMetadata)]
 pub(crate) struct StdlibModuleShadowing {
     name: String,
diff --git a/crates/ruff_workspace/src/options.rs b/crates/ruff_workspace/src/options.rs
index 95851353a2..abfedd2c35 100644
--- a/crates/ruff_workspace/src/options.rs
+++ b/crates/ruff_workspace/src/options.rs
@@ -1149,6 +1149,10 @@ pub struct Flake8BuiltinsOptions {
         example = "builtins-strict-checking = false"
     )]
     /// Compare module names instead of full module paths.
+    ///
+    /// Used by [`A005` - `stdlib-module-shadowing`](https://docs.astral.sh/ruff/rules/stdlib-module-shadowing/).
+    ///
+    /// In preview mode the default value is `false` rather than `true`.
     pub builtins_strict_checking: Option<bool>,
 }
 
diff --git a/ruff.schema.json b/ruff.schema.json
index 6ee9cbc780..97dec43e9f 100644
--- a/ruff.schema.json
+++ b/ruff.schema.json
@@ -1026,7 +1026,7 @@
           }
         },
         "builtins-strict-checking": {
-          "description": "Compare module names instead of full module paths.",
+          "description": "Compare module names instead of full module paths.\n\nUsed by [`A005` - `stdlib-module-shadowing`](https://docs.astral.sh/ruff/rules/stdlib-module-shadowing/).\n\nIn preview mode the default value is `false` rather than `true`.",
           "type": [
             "boolean",
             "null"