From 6d872cd1cd3b986a7f9b2c81020b3eabbb2ac9e4 Mon Sep 17 00:00:00 2001
From: Russell Keith-Magee <russell@keith-magee.com>
Date: Sat, 22 Feb 2025 16:30:30 +0800
Subject: [PATCH] gh-129712: Document the wheels tags corresponding to each
 universal SDK. (GH-130389)

Document the architectures supported by macOS universal SDK configuration flags,
and add details on wheel tag naming.
(cherry picked from commit 474c388740ca5f8060c074f517dd14c54409126f)

Co-authored-by: Russell Keith-Magee <russell@keith-magee.com>
---
 Doc/using/configure.rst                       | 22 ++++++++++++-------
 Mac/README.rst                                | 10 +++++++++
 ...-02-21-08-44-31.gh-issue-129712.4AcfWQ.rst |  2 ++
 3 files changed, 26 insertions(+), 8 deletions(-)
 create mode 100644 Misc/NEWS.d/next/Documentation/2025-02-21-08-44-31.gh-issue-129712.4AcfWQ.rst

diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst
index fed1d1e2c75940..6df75ac9e0b6cd 100644
--- a/Doc/using/configure.rst
+++ b/Doc/using/configure.rst
@@ -659,14 +659,20 @@ See ``Mac/README.rst``.
 
    Options:
 
-   * ``universal2``;
-   * ``32-bit``;
-   * ``64-bit``;
-   * ``3-way``;
-   * ``intel``;
-   * ``intel-32``;
-   * ``intel-64``;
-   * ``all``.
+   * ``universal2`` (x86-64 and arm64);
+   * ``32-bit`` (PPC and i386);
+   * ``64-bit``  (PPC64 and x86-64);
+   * ``3-way`` (i386, PPC and x86-64);
+   * ``intel`` (i386 and x86-64);
+   * ``intel-32`` (i386);
+   * ``intel-64`` (x86-64);
+   * ``all``  (PPC, i386, PPC64 and x86-64).
+
+   Note that values for this configuration item are *not* the same as the
+   identifiers used for universal binary wheels on macOS. See the Python
+   Packaging User Guide for details on the `packaging platform compatibility
+   tags used on macOS
+   <https://packaging.python.org/en/latest/specifications/platform-compatibility-tags/#macos>`_
 
 .. option:: --with-framework-name=FRAMEWORK
 
diff --git a/Mac/README.rst b/Mac/README.rst
index e32566d5475ae3..8a6e52725615aa 100644
--- a/Mac/README.rst
+++ b/Mac/README.rst
@@ -200,6 +200,16 @@ a ``python3.x-32`` binary and use the value of ``sys.executable`` as the
 Likewise, use ``python3.x-intel64`` to force execution in ``x86_64`` mode
 with ``universal2`` binaries.
 
+3. How do I specify binary universal wheels
+-------------------------------------------
+
+Binary wheels can also be universal. The platform tag name used to identify
+universal binary wheels differs from the naming scheme used when configuring a
+universal build with ``--with-universal-archs``. See the Python Packaging User
+Guide for details on the `packaging platform compatibility tags used on macOS
+<https://packaging.python.org/en/latest/specifications/platform-compatibility-tags/#macos>`_.
+
+
 Building and using a framework-based Python on macOS
 ====================================================
 
diff --git a/Misc/NEWS.d/next/Documentation/2025-02-21-08-44-31.gh-issue-129712.4AcfWQ.rst b/Misc/NEWS.d/next/Documentation/2025-02-21-08-44-31.gh-issue-129712.4AcfWQ.rst
new file mode 100644
index 00000000000000..82ad17c199a65e
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2025-02-21-08-44-31.gh-issue-129712.4AcfWQ.rst
@@ -0,0 +1,2 @@
+The wheel tags supported by each macOS universal SDK option are now
+documented.