PEP 632: Updates from day 1 of reviews (#1582)

* Clarified some text
* Add link to setuptools's migration page

pep-0632.rst

@@ -14,9 +14,10 @@ Abstract
 The distutils module [1]_ has for a long time recommended using the
 setuptools package [2]_ instead. Setuptools has recently integrated a
 complete copy of distutils and is no longer dependent on the standard
-library [3]_. Pip has silently replaced distutils with setuptools when
-building packages for a long time already. It is time to remove it
-from the (public part of the) standard library.
+library [3]_. Pip has been silently replacing distutils with
+setuptools when installing packages for a long time already, and the
+distutils documentation has stated that it is being phased out since
+2014 (or earlier). It is time to remove it from the standard library.
 
 
 Motivation
@@ -45,16 +46,16 @@ As a result, the second last major dependency on distutils is gone and
 there is no need to keep it in the standard library.
 
 The final dependency on distutils is CPython itself, which uses it to
-build the native extension modules in the standard library (except on
+build native extension modules in the standard library (except on
 Windows). Because this is a CPython build-time dependency, it is
 possible to continue to use distutils for this specific case without
 it being part of the standard library.
 
 Deprecation and removal will make it obvious that issues should be
 fixed in the setuptools project, and will reduce a source of bug
-reports and test maintenance that is unnecessary. It will also help
-promote the development of alternative build backends, which can now
-be supported more easily thanks to PEP 517.
+reports and unnecessary test maintenance. It will also help promote
+the development of alternative build backends, which can now be
+supported more easily thanks to PEP 517. [4]_
 
 
 Specification
@@ -93,6 +94,14 @@ comments:
 * Lib/_osx_support.py
 * Modules/_decimal/tests/formathelper.py
 
+The following Tools in CPython also refer to distutils. Note that none
+of these are installed with CPython:
+
+* PC/layout (references will be removed)
+* Tools/msi (references will be removed)
+* Tools/peg_generator (will be adapted to a different build tool)
+* Tools/test2to3 (example project will be removed)
+
 As the distutils code is already included in setuptools, there is no
 need to republish it in any other form. Those who require access to
 the functionality should use setuptools or an alternative build
@@ -104,20 +113,23 @@ Backwards Compatibility
 Code that imports distutils will no longer work from Python 3.12.
 
 The suggested migration path is to use the equivalent (though not
-identical) imports from setuptools.
+identical) imports from setuptools (see [5]_), or to migrate to an
+alternative build backend (see PEP 517 [4]_).
 
-Compatibility shims already exist in setuptools and pip to
-transparently migrate old code, however, these are controlled by
-external projects and are in no way bound by this PEP. Consult their
-latest documentation for migration advice.
+Code already exists in setuptools to transparently switch ``setup.py``
+files using distutils onto their equivalents, and so most working
+build scripts are already known to work with setuptools. Such scripts
+may need to update their import statements. Consult the setuptools
+documentation for specific migration advice. [5]_
 
-Some projects use alternate sets of shims over distutils, notably,
-numpy.distutils. [4]_ Where known, these projects have been informed.
+Some projects use alternate sets of patches over distutils, notably,
+numpy.distutils. [6]_ Projects that we know are doing this have been
+informed.
 
-Many use custom commands or more narrowly scoped patches, mostly
-constrained to ``setup.py`` files. As these packages are already
-subject to setuptools being injected by pip, we expect minimal
-disruption as a result of distutils being removed.
+Many build scripts use custom commands or narrowly scoped patches. As
+these packages are already subject to setuptools overriding distutils,
+we expect minimal disruption as a result of distutils being removed.
+Scripts may still need to be updated to avoid importing distutils.
 
 
 Reference Implementation
@@ -147,7 +159,13 @@ References
 .. [3] setuptools Issue #417 - Adopt distutils
    (https://github.com/pypa/setuptools/issues/417)
 
-.. [4] Packaging (numpy.distutils)
+.. [4] PEP 517 - A build-system independent format for source trees
+   (https://www.python.org/dev/peps/pep-0517/)
+
+.. [5] Porting from Distutils
+   (https://setuptools.readthedocs.io/en/latest/distutils-legacy.html)
+
+.. [6] Packaging (numpy.distutils)
    (https://numpy.org/doc/stable/reference/distutils.html)