PEP 632: Allow fixes during deprecation period and add migration and rejected ideas. (#1600)

pep-0632.rst

@@ -65,7 +65,9 @@ Specification
 
 In Python 3.10 and 3.11, distutils will be formally marked as
 deprecated. All known issues will be closed at this time.
-``import distutils`` will raise a deprecation warning.
+``import distutils`` will raise a deprecation warning. New issues that
+would be considered release blocking may still be fixed, but support
+for new tools or platforms will not be added.
 
 During Python 3.10 and 3.11, uses of distutils within the standard
 library may change to use alternative APIs.
@@ -149,6 +151,89 @@ for CPython's native module builds without relying on the standard
 library copy of distutils.
 
 
+Migration Advice
+================
+
+.. note::
+   This section suggests some alternative replacements for popular
+   functionality that is being formally deprecated with this PEP. It
+   is current at time of writing, but is not kept up to date.
+
+For these modules or types, ``setuptools`` is the best substitute:
+
+* ``distutils.ccompiler``
+* ``distutils.cmd.Command``
+* ``distutils.command``
+* ``distutils.config``
+* ``distutils.core.Distribution``
+* ``distutils.errors``
+
+For these modules or types, use the standards-defined Python Packaging
+Authority packages specified:
+
+* ``distutils.version`` - use ``packaging``
+
+For these modules or functions, use the standard library module shown:
+
+* ``distutils.fancy_getopt`` - use ``argparse``
+* ``distutils.spawn.find_executable`` - use ``shutil.which``
+* ``distutils.spawn.spawn`` - use ``subprocess.run``
+* ``distutils.sysconfig`` - use ``sysconfig``
+* ``distutils.util.get_platform`` - use ``platform``
+
+For these functions, and any others not mentioned here, you will need
+to reimplement the functionality yourself. The legacy documentation
+can be found at https://docs.python.org/3.9/distutils/apiref.html
+
+* ``distutils.dir_util.create_tree``
+* ``distutils.util.change_root``
+* ``distutils.util.strtobool``
+
+
+Rejected Ideas
+==============
+
+Deprecate but do not delete
+---------------------------
+
+The primary concern with this approach is that distutils most
+frequently breaks because of platform differences, which means that
+without maintenance, it will stop working out-of-sync with any
+Python release. This makes it impossible for libraries to reliably
+detect when they will stop working.
+
+In contrast, this PEP proposes a concrete date, known well in advance,
+when distutils will stop working, and commits to not breaking the API
+before that time. This gives maintainers a predictable schedule,
+ensures any breakage occurs at a point where users will already be
+expecting changed behavior, and provides a reliable detection
+mechanism (specifically, that ``import distutils`` raises).
+
+Finally, as long as distutils remains in the standard library in any
+form, it will interfere with third-party packages that provide shims
+or replacements, including setuptools. Completely removing the
+package at a known version makes it possible for third-parties to
+safely use a substitute.
+
+
+Only deprecate the setuptools-like functionality
+------------------------------------------------
+
+This suggestion assumes that there exists a volunteer to maintain
+whatever is left, which is not true. It also implies that anybody
+knows which functionality should remain, which as seen in the
+discussions is not at all clear.
+
+Most helper functions in distutils already have supported (and
+improved) alternatives, often in the standard library, and there is
+little that can be done to the legacy versions without breaking
+compatibility. (And any break requiring maintainers to update their
+code is essentially equivalent to requiring them to import a different
+function.)
+
+The last point from the previous section also applies here.
+
+
 References
 ==========