@@ -30,10 +30,41 @@ requisite library is ``setuptools``. Specify the build backend in a
3030 requires = ["setuptools"]
3131 #...
3232
33- Please note also to include any other ``setuptools `` plugins
33+ Also include any other ``setuptools `` plugins
3434(e.g., :pypi: `setuptools_scm `, :pypi: `setuptools-golang `, :pypi: `setuptools-rust `)
3535or build-time dependency (e.g., :pypi: `Cython `, :pypi: `cppy `, :pypi: `pybind11 `).
3636
37+ .. code-block :: toml
38+
39+ [build-system]
40+ requires = ["setuptools", "cython", "setuptools_scm"]
41+
42+
43+ If the project depends on a feature introduced in a specific version of Setuptools,
44+ it is good practice to specify it as a lower bound:
45+
46+ .. code-block :: toml
47+
48+ [build-system]
49+ requires = ["setuptools >= 61.2"]
50+
51+ Some may be tempted to also include an upper-bound for yet unreleased major
52+ versions (e.g. ``setuptools <= 70 ``) or pin to a specific version (e.g.
53+ ``setuptools == 70.0.4 ``) in order to avoid the project being uninstallable
54+ should those backward-incompatible changes affect this release of the project.
55+ Setuptools maintainers recommend strongly against this precautionary approach.
56+ The team primarily maintains one release, the latest monotonically-increasing
57+ release, and encourages users to use that latest release (work at HEAD). As a
58+ result, the team is cognizant of and takes responsibility for making
59+ backward-incompatible changes and aims to mitigate the impact of any breaking
60+ changes prior to releasing that change. By pinning against an unreleased
61+ version, it causes toil (maintenance burden) for each and every project that
62+ does the pinning (and the consumers that use it) and increases the risk of
63+ erosion if maintenance is unsustained. This tradeoff between reproducibility
64+ and compatibility is especially stark because Setuptools frequently releases
65+ backward-incompatible releases for a variety of reasons, many which won't
66+ affect a given project.
67+
3768.. note ::
3869 In previous versions of ``setuptools ``,
3970 the ``setup_requires `` keyword performed a similar function but is
0 commit comments