docs: Add a note about historical `wheel` use in `requires`

Add a note explaining that the `wheel` requirement that used to be
historically used in documentation was incorrect.  This also explains
why it can frequently be found in existing projects, and what problems
it causes.  I find myself repeatedly explaining it, so I think having
a single official source would be better.

Incorporates suggestions from Anderson Bravalheri.

1 files changed, 11 insertions, 0 deletions

diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst
index bf92f6a2..ead8209d 100644
--- a/docs/userguide/quickstart.rst
+++ b/docs/userguide/quickstart.rst
@@ -56,6 +56,17 @@ 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::
+
+   Historically this documentation has unnecessarily listed ``wheel``
+   in the ``requires`` list, and many projects still do that. This is
+   not recommended. The backend automatically adds ``wheel`` dependency
+   when it is required, and listing it explicitly causes it to be
+   unnecessarily required for source distribution builds.
+   You should only include ``wheel`` in `requires` if you need to explicitly
+   access it during build time (e.g. if your project needs a ``setup.py``
+   script that imports ``wheel``).
+
 In addition to specifying a build system, you also will need to add
 some package information such as metadata, contents, dependencies, etc.
 This can be done in the same ``pyproject.toml`` [#beta]_ file,