Merge pull request numpy#22154 from rgommers/warning-pin-setuptools

DOC: add more prominent warnings to pin setuptools

Author: mattip

doc/source/dev/depending_on_numpy.rst

@@ -104,9 +104,14 @@ specify the version with ``==`` to the lowest supported version. For your other
 build dependencies you can probably be looser, however it's still important to
 set lower and upper bounds for each dependency. It's fine to specify either a
 range or a specific version for a dependency like ``wheel`` or ``setuptools``.
-It's recommended to set the upper bound of the range to the latest already
-released version of ``wheel`` and ``setuptools`` - this prevents future
-releases from breaking your packages on PyPI.
+
+.. warning::
+
+    Note that ``setuptools`` does major releases often and those may contain
+    changes that break ``numpy.distutils``, which will *not* be updated anymore
+    for new ``setuptools`` versions. It is therefore recommended to set an
+    upper version bound in your build configuration for the last known version
+    of ``setuptools`` that works with your build.
 
 
 Runtime dependency & version ranges

doc/source/reference/distutils.rst

@@ -9,6 +9,14 @@ Packaging (:mod:`numpy.distutils`)
    ``numpy.distutils`` is deprecated, and will be removed for
    Python >= 3.12. For more details, see :ref:`distutils-status-migration`
 
+.. warning::
+
+   Note that ``setuptools`` does major releases often and those may contain
+   changes that break ``numpy.distutils``, which will *not* be updated anymore
+   for new ``setuptools`` versions. It is therefore recommended to set an
+   upper version bound in your build configuration for the last known version
+   of ``setuptools`` that works with your build.
+
 NumPy provides enhanced distutils functionality to make it easier to
 build and install sub-packages, auto-generate code, and extension
 modules that use Fortran-compiled libraries. To use features of NumPy