Merge branch 'main' into hint-on-resolution-impossible-when-no-packages-are-available

Author: notatallshaw

docs/html/cli/pip.rst

@@ -77,7 +77,7 @@ when decision is needed.
 .. _`2-build-system-interface`:
 .. rubric:: Build System Interface
 
-This is now covered in :doc:`../reference/build-system/index`.
+This is now covered in :doc:`../reference/build-system`.
 
 .. _`General Options`:
 

docs/html/cli/pip_freeze.rst

@@ -23,6 +23,15 @@ Description
 
 .. pip-command-description:: freeze
 
+.. note::
+   By default, ``pip freeze`` omits bootstrap packaging tools so the output
+   focuses on your project’s dependencies. On Python **3.11 and earlier**
+   this excludes ``pip``, ``setuptools``, ``wheel`` and ``distribute``; on
+   Python **3.12 and later** only ``pip`` is excluded. Use ``--all`` to
+   include those packages when you need a complete environment snapshot.
+   ``pip freeze`` reports what is installed; it does **not** compute a
+   lockfile or a solver result.
+
 
 Options
 =======

docs/html/cli/pip_install.rst

@@ -255,7 +255,7 @@ This is now covered in :doc:`../topics/local-project-installs`.
 .. _`0-build-system-interface`:
 .. rubric:: Build System Interface
 
-This is now covered in :doc:`../reference/build-system/index`.
+This is now covered in :doc:`../reference/build-system`.
 
 .. _`pip install Options`:
 

docs/html/cli/pip_wheel.rst

@@ -28,7 +28,7 @@ Description
 .. _`1-build-system-interface`:
 .. rubric:: Build System Interface
 
-This is now covered in :doc:`../reference/build-system/index`.
+This is now covered in :doc:`../reference/build-system`.
 
 Differences to ``build``
 ------------------------

docs/html/reference/build-system/pyproject-toml.md renamed to docs/html/reference/build-system.md

@@ -1,9 +1,28 @@
-# `pyproject.toml`
+(build-interface)=
 
 ```{versionadded} 10.0
 
 ```
 
+```{versionchanged} 23.1
+The legacy interface where pip could invoke `setup.py install`
+in some circumstances was removed,
+in favor of the fallback behavior described below.
+```
+
+```{versionchanged} 25.3
+The legacy interface where pip could invoke `setup.py build_wheel` or
+`setup.py develop` in some circumstances was removed,
+in favor of the fallback behavior described below..
+```
+
+# Build System Interface
+
+When dealing with installable source distributions of a package, pip does not
+directly handle the build process for the package. This responsibility is
+delegated to "build backends" -- also known as "build systems". This means
+that pip needs an interface, to interact with these build backends.
+
 Modern Python packages can contain a `pyproject.toml` file, first introduced in
 {pep}`518` and later expanded in {pep}`517`, {pep}`621` and {pep}`660`.
 This file contains build system requirements and information, which are used by
@@ -96,16 +115,6 @@ For performing editable installs, pip will use {pep}`660`
 `build_wheel_for_editable` hook that has to be provided by the build backend.
 The wheels generated using this mechanism are not cached.
 
-```{admonition} Compatibility fallback
-If this hook is missing on the build backend _and_ there's a `setup.py` file
-in the project, pip will fallback to the legacy setup.py-based editable
-installation.
-
-This is considered a stopgap solution until setuptools adds support for
-{pep}`660`, at which point this functionality will be removed; following pip's
-regular {ref}`deprecation policy <Deprecation Policy>`.
-```
-
 ### Backend Configuration
 
 Build backends have the ability to accept configuration settings, which can
@@ -125,8 +134,7 @@ files.
 ## Build output
 
 It is the responsibility of the build backend to ensure that the output is
-in the correct encoding, as described in {pep}`517`. This likely involves
-dealing with [the same challenges as pip has for legacy builds](build-output).
+in the correct encoding, as described in {pep}`517`.
 
 ## Fallback Behaviour
 
@@ -138,7 +146,8 @@ https://setuptools.pypa.io/en/stable/userguide/quickstart.html#basic-use).
 ```
 
 If a project does not have a `pyproject.toml` file containing a `build-system`
-section, it will be assumed to have the following backend settings:
+section, and contains a `setup.py` it will be assumed to have the following
+backend settings:
 
 ```toml
 [build-system]

docs/html/reference/build-system/index.md

@@ -6,7 +6,7 @@ interoperability standards that pip utilises/implements.
 ```{toctree}
 :titlesonly:
 
-build-system/index
+build-system
 requirement-specifiers
 requirements-file-format
 installation-report