gh-149202: Highlight PEP 831 in What's New for Python 3.15 (#149390)

diff --git a/Doc/whatsnew/3.15.rst b/Doc/whatsnew/3.15.rst
index 7f12cc04a460d466fce1b4a1b997bdb0ffccf19c..e98c483baec823008da892983f4db53ec457cc03 100644 (file)
--- a/Doc/whatsnew/3.15.rst
+++ b/Doc/whatsnew/3.15.rst
@@ -75,6 +75,8 @@ Summary -- Release highlights
   profiling tools <whatsnew315-profiling-package>`
 * :pep:`799`: :ref:`Tachyon: High frequency statistical sampling profiler
   <whatsnew315-sampling-profiler>`
+* :pep:`831`: :ref:`Frame pointers are enabled by default for improved
+  system-level observability <whatsnew315-pep831>`
 * :pep:`798`: :ref:`Unpacking in comprehensions
   <whatsnew315-unpacking-in-comprehensions>`
 * :pep:`686`: :ref:`Python now uses UTF-8 as the default encoding
@@ -86,7 +88,6 @@ Summary -- Release highlights
 * :pep:`782`: :ref:`A new PyBytesWriter C API to create a Python bytes object
   <whatsnew315-pybyteswriter>`
 * :pep:`803`: :ref:`Stable ABI for Free-Threaded Builds <whatsnew315-abi3t>`
-* :pep:`831`: :ref:`Frame pointers everywhere <whatsnew315-frame-pointers>`
 * :ref:`The JIT compiler has been significantly upgraded <whatsnew315-jit>`
 * :ref:`Improved error messages <whatsnew315-improved-error-messages>`
 * :ref:`The official Windows 64-bit binaries now use the tail-calling interpreter
@@ -376,6 +377,39 @@ available output formats, profiling modes, and configuration options.
 (Contributed by Pablo Galindo and László Kiss Kollár in :gh:`135953` and :gh:`138122`.)
 
 
+.. _whatsnew315-pep831:
+
+:pep:`831`: Frame pointers enabled by default
+---------------------------------------------
+
+CPython is now built with frame pointers by default on platforms that support
+them.  This uses the compiler flags ``-fno-omit-frame-pointer`` and
+``-mno-omit-leaf-frame-pointer``, making native stack unwinding faster and
+more reliable for system profilers, debuggers, crash analysis tools, and
+eBPF-based observability tools.
+
+The flags are exposed through :mod:`sysconfig`, so extension modules built by
+tools that consume Python's build configuration inherit frame pointers by
+default.  This propagation is intentional: mixed Python/native profiling needs
+an unbroken frame-pointer chain through the interpreter, extension modules,
+embedding applications, and native libraries.
+
+.. important::
+
+   Third-party build backends and native build systems should preserve these
+   flags when they consume Python's :mod:`sysconfig` values.  Build systems
+   that compile C, C++, Rust, or other native code without inheriting Python's
+   compiler flags should enable equivalent frame-pointer flags themselves.  A
+   single native component built without frame pointers can break stack
+   unwinding for the whole Python process.
+
+.. seealso:: :pep:`831` for further details.
+
+(Contributed by Pablo Galindo Salgado and Savannah Ostrowski in
+:gh:`149201`; PEP 831 written by Pablo Galindo Salgado, Ken Jin, and
+Savannah Ostrowski.)
+
+
 .. _whatsnew315-unpacking-in-comprehensions:
 
 :pep:`798`: Unpacking in Comprehensions
@@ -2378,16 +2412,6 @@ Build changes
   and :option:`-X dev <-X>` is passed to the Python or Python is built in :ref:`debug mode <debug-build>`.
   (Contributed by Donghee Na in :gh:`141770`.)
 
-.. _whatsnew315-frame-pointers:
-
-* CPython is now built with frame pointers enabled by default
-  (:pep:`831`). Pass :option:`--without-frame-pointers` to opt out.
-  Authors of C extensions and native libraries built with custom build
-  systems should add ``-fno-omit-frame-pointer`` and
-  ``-mno-omit-leaf-frame-pointer`` to their own ``CFLAGS`` to keep the
-  unwind chain intact.
-  (Contributed by Pablo Galindo Salgado and Savannah Ostrowski in :gh:`149201`.)
-
 .. _whatsnew315-windows-tail-calling-interpreter:
 
 * 64-bit builds using Visual Studio 2026 (MSVC 18) may now use the new