Re: Build platform guarantees, docs, tests, and snakes in the garden

[Paolo Bonzini <pbonzini@redhat.com>]

On 6/5/25 21:35, John Snow wrote:
> 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.

The *ideal* solution would be to:

- accept: 4.3.2 or newer, which is what Ubuntu 22.04 has

- install: 6.2.1, which is what supports Python 3.13

This lets all supported distros build documentation if they use the 
default Python runtime.  It would still require a couple hacks in 
compat.py: SOURCE_LOCATION_FIX and nested_parse_with_titles().

I am not sure however whether to count the latter, for two reasons. 
First, it has this:

     # necessary so that the child nodes get the right source/line set
     content_node.document = directive.state.document

so it is not a pure compatibility hack.  Second, and opposite, currently 
none of the uses of nested_parse_with_titles() go through compat.py's 
version, therefore it probably can be removed altogether.

That leaves only SOURCE_LOCATION_FIX.

As an aside, if the compat.py hacks survive, I would add comments to 
document which distros need the hacks.

> 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?

Certainly for platforms not using the default Python runtime, which 
right now is only SLES.  For others...

> How highly do we value the ability to locally 
> build docs for any given release?

... I think I value this a bit higher than Markus, but not really 
because of offline builds.  Rather, keeping the "accepted" key lower 
(i.e. supporting the packaged sphinx on a wide range of distros) makes 
it easier to bump the "installed" key when needed, as in this failure to 
run 5.3.0 under Python 3.13.

This time there was a version that works on both the oldest and newest 
Python that we support, but there may not always be one because sphinx 
is all too happy at dropping support for EOL'd versions of Python.

Paolo

> 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
>