gh-148641: Flesh out PEP 829 for What's New (#149347)

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

diff --git a/Doc/whatsnew/3.15.rst b/Doc/whatsnew/3.15.rst
index 3cf69718e63b28e2f100879f043de858021445e3..1a5e5fe2fc0be6c0a3f1b57c4fe6f1df246c520e 100644 (file)
--- a/Doc/whatsnew/3.15.rst
+++ b/Doc/whatsnew/3.15.rst
@@ -81,6 +81,7 @@ Summary -- Release highlights
   <whatsnew315-unpacking-in-comprehensions>`
 * :pep:`686`: :ref:`Python now uses UTF-8 as the default encoding
   <whatsnew315-utf8-default>`
+* :pep:`829`: :ref:`Package startup configuration files <whatsnew315-startup-files>`
 * :pep:`728`: :ref:`TypedDict with typed extra items <whatsnew315-typeddict>`
 * :pep:`747`: :ref:`Annotating type forms with TypeForm
   <whatsnew315-typeform>`
@@ -94,7 +95,6 @@ Summary -- Release highlights
 * :ref:`Improved error messages <whatsnew315-improved-error-messages>`
 * :ref:`The official Windows 64-bit binaries now use the tail-calling interpreter
   <whatsnew315-windows-tail-calling-interpreter>`
-* :pep:`829`: Package Startup Configuration Files
 
 New features
 ============
@@ -452,6 +452,31 @@ agen() for x in a)``.
 
 (Contributed by Adam Hartz in :gh:`143055`.)
 
+.. _whatsnew315-startup-files:
+
+:pep:`829`: Package startup configuration files
+-----------------------------------------------
+
+Loaded by the :mod:`site` module when ``-S`` is not given, :ref:`.pth files <site-pth-files>`
+can contain lines that both extend :data:`sys.path` and execute arbitrary code
+when the line starts with ``import`` (followed by a space or tab).  The latter
+functionality can be problematic, since it is difficult to know exactly what
+gets executed when Python starts up.
+
+As a step towards improving the ability to audit pre-start executable code,
+Python 3.15 introduces :ref:`.start files <site-start-files>` which contain entry point
+specifications of the form ``pkg.mod:callable`` where ``pkg.mod`` is the
+import path to the given callable.  When Python starts up, the callable is
+located and called with no arguments.
+
+``import`` lines in :file:`.pth` files are silently deprecated.  When a
+matching :file:`.start` file is found, ``import`` lines in :file:`.pth` files
+are ignored.  There is no change to :data:`sys.path` extension lines in
+:file:`.pth` files.
+
+(Contributed by Barry Warsaw in :gh:`148641`.)
+
+
 .. _whatsnew315-abi3t:
 
 :pep:`803` -- Stable ABI for Free-Threaded Builds