From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Fri, 3 Apr 2026 08:03:09 +0000 (+0200)
Subject: [3.13] gh-146907: Clarify ABI compatibility between debug and release builds (GH... 
X-Git-Tag: v3.13.13~24
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=1e60efd299a8e21fe937ce4a56951042ffef3033;p=thirdparty%2FPython%2Fcpython.git

[3.13] gh-146907: Clarify ABI compatibility between debug and release builds (GH-146925) (GH-147972)

(cherry picked from commit 03f3b9ade975e78a31bf776ff27ac6ac22fcb65a)

Co-authored-by: konsti <konstin@mailbox.org>
---

diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst
index 03039edc71a7..fde0ddba9f9d 100644
--- a/Doc/using/configure.rst
+++ b/Doc/using/configure.rst
@@ -708,9 +708,11 @@ See also the :ref:`Python Development Mode <devmode>` and the
 :option:`--with-trace-refs` configure option.
 
 .. versionchanged:: 3.8
-   Release builds and debug builds are now ABI compatible: defining the
+   Release builds are now ABI compatible with debug builds: defining the
    ``Py_DEBUG`` macro no longer implies the ``Py_TRACE_REFS`` macro (see the
-   :option:`--with-trace-refs` option).
+   :option:`--with-trace-refs` option). However, debug builds still expose
+   more symbols than release builds and code built against a debug build is not
+   necessarily compatible with a release build.
 
 
 Debug options
diff --git a/Doc/whatsnew/3.8.rst b/Doc/whatsnew/3.8.rst
index ea809931a316..308f41abc74c 100644
--- a/Doc/whatsnew/3.8.rst
+++ b/Doc/whatsnew/3.8.rst
@@ -207,14 +207,15 @@ subdirectories).
 Debug build uses the same ABI as release build
 -----------------------------------------------
 
-Python now uses the same ABI whether it's built in release or debug mode. On
-Unix, when Python is built in debug mode, it is now possible to load C
-extensions built in release mode and C extensions built using the stable ABI.
-
-Release builds and :ref:`debug builds <debug-build>` are now ABI compatible: defining the
-``Py_DEBUG`` macro no longer implies the ``Py_TRACE_REFS`` macro, which
-introduces the only ABI incompatibility. The ``Py_TRACE_REFS`` macro, which
-adds the :func:`sys.getobjects` function and the :envvar:`PYTHONDUMPREFS`
+The ABI of Python :ref:`debug builds <debug-build>`  is now compatible with
+Python release builds. On Unix, when Python is built in debug mode, it is now
+possible to load C extensions built in release mode and C extensions built
+using the stable ABI. The inverse is not true, as debug builds expose
+additional symbols not available in release builds.
+
+Defining the ``Py_DEBUG`` macro no longer implies the ``Py_TRACE_REFS`` macro,
+which introduces the only ABI incompatibility. The ``Py_TRACE_REFS`` macro,
+which adds the :func:`sys.getobjects` function and the :envvar:`PYTHONDUMPREFS`
 environment variable, can be set using the new :option:`./configure
 --with-trace-refs <--with-trace-refs>` build option.
 (Contributed by Victor Stinner in :issue:`36465`.)