Hi, I've long been a little confused about the specifics of our build platform guarantee and how it applies to documentation and testing.
My *current* understanding is that our build platform guarantee applies to both unit tests and building documentation, but that this requirement may not be as absolute as I imagine it. The way I have endeavored to manage the Python tooling in our tree so far is to preserve, without fail, our ability to perform fully offline builds on all supported platforms (provided that the right distro repo packages are available). The Python virtual environment created at configure time bends over backwards to use system packages *whenever possible*, and the list of exceptions - notably Meson itself - uses vendored packages only in very specific cases where it is possible to vendor such packages. Fetching packages from PyPI is generally offered only as a convenience for developer workstations to, in general, save developers from having to know anything about Python. (I think I've done a good job there, to be honest!) (Notably: Meson is pure python and has no dependencies, so it is possible to vendor it for offline builds. Tools like Sphinx, however, have many dependencies and are not so easily vendored. Thus, we have created a tenuous arrangement where we are allowed to use versions of Meson that otherwise would break our build platform guarantee.) Lately, we've had some issues with the wide range of Sphinx versions we support presenting various cross-platform difficulties. In particular, Akihiko Odaki has sent patches to bump our Sphinx version to at least 6.2.1, because platforms with Python 3.13.1 can no longer run Sphinx 3.x at all, so having that be our "default install version" causes issues on newer platforms. However, if we take as iron-clad our commitment to the build platform promise -- *and* guarantee offline/tarball builds as well -- then Debian 12 (as an example) only offers Sphinx 5.3.0 and not newer unless we allow internet access to fetch Sphinx 6.2.1. This is not a problem for developer workstations at all, but I am unclear on what problems this may cause for tarball releases and downstream offline/isolated/reproducible builds, if any. In this case, we can (probably) "fix" the issue by continuing to allow older Sphinx while preferring a newer Sphinx version when it is missing, but then we lose the ability to make code cleanups and drop a lot of back-compat crud. If memory serves, there were other issues recently where older versions of Sphinx behaved differently from newer versions, causing intermittent failures that were hard to track down. What I'd like to know is: what precisely are our options in this scenario? Do we consider it acceptable for some platforms to be unable to build docs offline? How highly do we value the ability to locally build docs for any given release? Before I throw my weight behind any given option, I just want to know what we consider our non-negotiable obligations to be. Thanks, --js
