From 99d2c722ca5d58ef1360ed86a3252cc16bd84dfd Mon Sep 17 00:00:00 2001 From: "Jason R. Coombs" Date: Mon, 22 Jul 2024 09:39:50 -0400 Subject: [PATCH] Add documentation clarifying how to reliably install setuptools with its dependencies. Ref #4483 --- docs/userguide/quickstart.rst | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst index c4875d71fc..b0f1401e0e 100644 --- a/docs/userguide/quickstart.rst +++ b/docs/userguide/quickstart.rst @@ -7,7 +7,7 @@ Installation You can install the latest version of ``setuptools`` using :pypi:`pip`:: - pip install --upgrade setuptools + pip install --upgrade setuptools[core] Most of the times, however, you don't have to... @@ -56,6 +56,16 @@ containing a ``build-system`` section similar to the example below: This section declares what are your build system dependencies, and which library will be used to actually do the packaging. +.. note:: + + Package maintainers might be tempted to use ``setuptools[core]`` as the + requirement, given the guidance above. Avoid doing so, as the extra + is currently considered an internal implementation detail and is likely + to go away in the future and the Setuptools team will not support + compatibility for problems arising from packages published with this + extra declared. Vendored packages will satisfy the dependencies in + the most common isolated build scenarios. + .. note:: Historically this documentation has unnecessarily listed ``wheel``