From 5d0764a110df1780af544e17e4d4bf9c9196f722 Mon Sep 17 00:00:00 2001
From: sapunyangkut <302607731+sapunyangkut@users.noreply.github.com>
Date: Tue, 14 Jul 2026 09:19:46 +0800
Subject: [PATCH] Clarify package_dir recursive mapping.

---
 docs/deprecated/distutils/setupscript.rst | 17 +++++++++--------
 newsfragments/3359.doc.rst                |  2 ++
 2 files changed, 11 insertions(+), 8 deletions(-)
 create mode 100644 newsfragments/3359.doc.rst

diff --git a/docs/deprecated/distutils/setupscript.rst b/docs/deprecated/distutils/setupscript.rst
index de68a5c320..3749f600e5 100644
--- a/docs/deprecated/distutils/setupscript.rst
+++ b/docs/deprecated/distutils/setupscript.rst
@@ -96,14 +96,15 @@ written in the setup script as ::
 
     package_dir = {'foo': 'lib'}
 
-A ``package: dir`` entry in the ``package_dir`` dictionary implicitly
-applies to all packages below *package*, so the ``foo.bar`` case is
-automatically handled here.  In this example, having ``packages = ['foo',
-'foo.bar']`` tells the Distutils to look for :file:`lib/__init__.py` and
-:file:`lib/bar/__init__.py`.  (Keep in mind that although ``package_dir``
-applies recursively, you must explicitly list all packages in
-``packages``: the Distutils will *not* recursively scan your source tree
-looking for any directory with an :file:`__init__.py` file.)
+A ``package: dir`` entry in the ``package_dir`` dictionary implicitly applies
+the directory mapping to all packages below *package*.  It does not add those
+packages to the distribution automatically.  In this example, having
+``packages = ['foo', 'foo.bar']`` tells the Distutils to look for
+:file:`lib/__init__.py` and :file:`lib/bar/__init__.py`; the directory for
+``foo.bar`` is derived from the mapping for ``foo``.  You must still explicitly
+list every package in ``packages``: the Distutils will *not* recursively scan
+your source tree looking for directories containing an :file:`__init__.py`
+file.
 
 
 .. _listing-modules:
diff --git a/newsfragments/3359.doc.rst b/newsfragments/3359.doc.rst
new file mode 100644
index 0000000000..d3382a5c00
--- /dev/null
+++ b/newsfragments/3359.doc.rst
@@ -0,0 +1,2 @@
+Clarified that ``package_dir`` recursively maps package names to directories
+without automatically adding packages to a distribution.