From 76922021bc7790bb503c8af95a19cecbc65a61d3 Mon Sep 17 00:00:00 2001
From: "Aryan Singh K." <70511529+aryansk@users.noreply.github.com>
Date: Fri, 7 Aug 2026 00:55:31 +0530
Subject: [PATCH] Document packages_distributions metadata fallback

---
 docs/migration.rst           | 16 +++++++++++++++-
 newsfragments/526.bugfix.rst |  1 +
 2 files changed, 16 insertions(+), 1 deletion(-)
 create mode 100644 newsfragments/526.bugfix.rst

diff --git a/docs/migration.rst b/docs/migration.rst
index 3c700778..4210ac25 100644
--- a/docs/migration.rst
+++ b/docs/migration.rst
@@ -68,6 +68,21 @@ functions for easy access to the most common metadata:
 - :ref:`files` provides file-like access to the data blobs backing
   the metadata.
 
+.. _packages-distributions:
+
+packages_distributions()
+========================
+
+``packages_distributions()`` maps importable top-level package and module names
+to the distributions that provide them. When available, it uses the
+distribution's ``top_level.txt`` file before falling back to inferring names
+from the installed file list.
+
+``top_level.txt`` is a legacy, setuptools-specific metadata file rather than a
+requirement of the distribution metadata standards. Build backends are
+therefore not required to provide it, and the mapping may be incomplete when a
+distribution also does not expose enough file metadata for inference.
+
 pkg_resources.find_distributions()
 ==================================
 
@@ -81,4 +96,3 @@ pkg_resources.get_distribution()
 
 Similar to ``distributions``, the ``distribution()`` function provides
 access to a single distribution by name.
-
diff --git a/newsfragments/526.bugfix.rst b/newsfragments/526.bugfix.rst
new file mode 100644
index 00000000..2d09fe16
--- /dev/null
+++ b/newsfragments/526.bugfix.rst
@@ -0,0 +1 @@
+Document the legacy ``top_level.txt`` dependency and fallback behavior of ``packages_distributions()``.