Description

ncoghlan

opened on Aug 2, 2025

Issue body actions

Issue Description

In #1880, questions were raised regarding the maintainability of the example build backend dependencies. Specifically:

• how to handle backends that recommend upper bounds on the backend version (while tools that create per-package build environments can handle those without issue, they are a potential problem for build systems that aim to create unified build environments, such as those for Linux distros and from-source stack building projects like fromager)
• how to ensure we're not recommending excessively outdated versions of the backends

Some flavour of automation could help with the latter problem, but the former problem is a trickier one.

Code of Conduct

• I am aware that participants in this repository must follow the PSF Code of Conduct.

Activity

1. sinoroc commented on Aug 3, 2025

   

   sinoroc

   on Aug 3, 2025

   Contributor

   More actions

   As I said over there, I wonder if the guide should maintain those version numbers at all. Maybe the guide should rather focus on teaching what versions constraints are, why they matter, how to use them, and when to use them. The guide should also nudge the readers to refer to each project's documentation (and change log) to find project specific and up to date advice (actual version numbers), i.e. things the guide's authors might not want to be held responsible for.

   How to ensure we're not recommending excessively outdated versions of the backends? Some flavour of automation could help with the problem.

   Is it something Dependabot could do, or be tricked into doing? It seems Dependabot might have support for build-system.requires.
2. webknjaz commented on Aug 14, 2025

   

   webknjaz

   on Aug 14, 2025

   Member

   More actions

   I don't think Dependabot is the answer. The guide should include minimum versions that introduce features being demonstrated. But since some backends are at odds with downstreams, we should at least include a warning in the example widget talking about the dangers and referencing the discussion contributed @ #1791.

   Talking about the constraints is useful but I think the context is not exactly the same. Constraints are useful for the upstreams to keep the CI stable and the builds reproducible.
   It would be nice to have the actual concrete versions included in the metadata of sdists/wheels. They'd be useful for future troubleshooting and knowing what actually worked at the time a project published their dists to PyPI.

   At EuroPython somebody (I don't remember the name) suggested that this might require something like a core packaging metadata change. I think @uranusjr and I (IIRC) suggested that it's possible to have a PoC without a metadata update, though.
3. notatallshaw commented on Aug 14, 2025

   

   notatallshaw

   on Aug 14, 2025

   Member

   More actions

   Taking a step back, who is this documentation targeted towards?

   For personal or private applications all of this is probably the wrong advice, and almost certainly the correct advise is either to pin to a major version, e.g. setuptools ~= 77.0, or pin to an exact version, e.g. setuptools == 70.3.0. And to regularly check for updates (preferably using automated tooling) to see if new build backend versions are still compatible with existing build.

   This pinning is required because no lock file yet offers build dependency locking, so it can not be recommended to have permissive requirements and but use a lock file for reproducible dependencies and builds.

   But I assume that the documentation is targeting open source library authors? Which makes sense on the one hand because we're probably all open source library maintainers here, but is odd in another because there's probably significantly more personal and private applications using Python than there are open source libraries.

   Personally I would like to see lock files, rather than constraints, offered by applications as part of their metadata, for users to be able to have the option to use the application authors predefined reproducible dependencies and builds, but there was significant push back on this idea: https://discuss.python.org/t/pre-pep-include-pylock-toml-files-inside-wheels/99385 / https://discuss.python.org/t/pre-pep-add-ability-to-install-a-package-with-reproducible-dependencies/99497 (although IMO the author of these threads didn't understand the rigors of providing a PEP).

   Reacted by sinoroc and Pierre Sassoulas

Issue actions