Support some form of "latest" for build.os

[askpatrickw]

Details

The new build.os setting only allows for a single very specific versioned value: ubuntu-20.04.

I help out on CircuitPython occasionally. Adafruit has ~300 CP library repos, plus an additional ~300 Arduino library repos.
Having to touch all these repos is very tedious when a version change is needed.

Proposed Change

I suggest changing build.os to support ubuntu AND ubuntu-20.04 as values. It should be documented that, for now, these are equivalent. That the version will be ubuntu-20.04, but in the future, ubuntu will be "latest LTS".

This would, for the time being, keep the functionality the same for RTD, but for groups with many repos, require less maintenance of the configuration.

[humitos]

HI @askpatrickw! This was done on purpose 😄 . Having a latest / ubuntu value or something pointing to the most recent version of something has the inverse problem that you are describing, but it also inverts the responsible of the breaking change --in case builds start failing.

With the current scenario, you are very explicit about the Ubuntu version you want to install. If you want to upgrade it, or you change it to a different and newer version, and builds start failing you know exactly why and you are able to solve it by yourself. Once you are happy with one repository you can do a bulk change for the others ~300 repositories.

On the other hand, with the latest / ubuntu scenario that installs the latest version of ubuntu, if Read the Docs upgrades the version of ubuntu from 20.04 to 21.04 and your builds start failing you won't know immediately why that happens and you will probably "blame" us because we broke your builds and now you have to pin to ubuntu-20.04 in ~300 repositories 😄

Actually, because of the last scenario described (and also being too permissive with sane defaults), we had to maintain a lot of weird things to make everybody happy and we were blocked from implementing new features for most of the users.

So, IMHO, I wouldn't implement something like latest for these things. I'm pinging @ericholscher @stsewd since they may have different opinions, tho.

[stsewd]

We already support setting python to 3 as alias for the latest version, I think it's useful to have a way to have the same for ubuntu, to be more specific about using the latest version I'd name it ubuntu-latest (note, that this doesn't necessarily mean the latest lts, but the latest version available on rtd).

About users having problems when a new version is available, I think we can just be explicit in our docs about this if they choose to use ubuntu-latest.

[askpatrickw]

As stsewd mentions, I could see something along the lines of the way you can specify "3" for "3.x". Something like ubtuntu-{majorversion} ex: "ubuntu-20" would work similarly to the way the build tools versioning works.

It make a lot of sense for all the things to work the same, or at least as similarly as possible.

[humitos]

I think we all think it's a nice feature and we all agree about its simple implementation. However, I have the same concerns for python.version: 3 key as well; and I would prefer to not have it working like that 😄

My point is that it's a nice feature while it works as we expected but we don't like it when it breaks, even if Read the Docs upgrades the versions properly. Besides, latest has its own meaning on Read the Docs that it may, or may not, differ from the real latest version of them (e.g. "latest Python in the community is currently 3.10.2" while "latest Python in Read the Docs is 3.10.0 right now". Note that this is not a huge problem because the difference is in the patch version, but it could be in the minor version as in 3.11 and 3.10. Then, upgrading the "latest Python in RTD" could break a lot of documentation projects producing those users to blame us/generating a lot of support requests/etc). This will definitely produce confusion for users.

That's about one software, Python version that, in theory, newer 3.x versions are able to run older 3.x code. However, if we talk about upgrading the base OS from Ubuntu 18.04 to Ubuntu 20.04 a lot of dependencies changed producing documentation projects to fail at a build or even worse, succeed but producing different results that are not easy to notice immediately.

In the past, potentially producing this breaking change to many documentation projects, had complicated things and stopped us to move forward (e.g. Docker images were frozen for years because of this reason).

So, that said, my point is "this is a good feature" but I'm sure "it will break" and "I don't think it's better UX to have it implemented" than "only give the user an explicit way of upgrading these versions" instead of adding magic in our side that does not match the current state of the reality.

[humitos]

Something like ubtuntu-{majorversion} ex: "ubuntu-20" would work similarly to the way the build tools versioning works.

Note that we only use LTS versions, so there won't be ubuntu-20.10 for example. Following this idea, ubuntu-20 would always be ubuntu-20.04 for Read the Docs and won't pick a newer version.

[askpatrickw]

Sorry, I was thinking the -04 could change for an LTS if there is a security fix. I'd not read the Ubuntu LTS scheme.

So only acceptable values today would be 20-04 and soon 22-04.

-p

[benjaoming]

General comment on using latest

In general, I really like being able to use latest to not have to manage documentation dependencies, version bumps and this kind of hamster wheel / Sisyphus work (often it has zero benefits to the project and its contents!). I think this is applicable to both the Ubuntu environment, Python, Sphinx and the sphinx-rtd-theme.

There are many settings (especially smaller projects) where in my mind as a documentation author, I am writing reST or Markdown and not managing a software project (except of course for maybe Sphinx extensions or API docs).

By not having to bother with bumping versions, I can lean back and only bother with versions when something eventually breaks. This saves me a lot of work. A good way to address the issue of "when something eventually breaks" could be to have scheduled builds that proactively catches these situations (but that can happen in the future).

I really want the use of latest to be an explicit option and also a choice. The use of latest should never be implicit, for instance I think that python3 is a weird option that doesn't clearly signal what is going on.

For the ubuntu-latest proposal, I would suggest ubuntu-lts-latest so it's more clear and so we have a way to deliberately handle non-LTS releases.

If a user chooses latest, they also choose a responsibility. I.e. the user is now responsible for maintaining an updated project that works on latest stable releases (of Ubuntu, Python, Sphinx or whatever they are working with).

We can announce changes to ubuntu-latest-lts or python3-latest in a general platform roadmap.

Latest and reproducible are opposites

Reproducible builds should be default. A user that does not want or need to understand a bunch of stuff about maintaining a software stack should be able to bootstrap a project that doesn't suddenly break for technical reasons.

Using latest in various settings should be a choice for people that know what they are doing and want the responsibility in case the project breaks.

[ericholscher]

I tend to agree with @benjaoming. I'm OK offering advanced users the option to have things break on them, as long as they are opting into it 👍

[benjaoming]

"reproducible by default, latest by choice" :D

Edit to make it rhyme: "reproducible by default, latest is your-eh-fault"

[humitos]

@benjaoming

For the ubuntu-latest proposal, I would suggest ubuntu-lts-latest so it's more clear and so we have a way to deliberately handle non-LTS releases.

I like this proposal.

I'd vote 👍🏼 to have this config if we are pretty explicit about what it means to our users and, in particular, to us. I'm saying this because in the past we have decided to not upgrade the latest version of something because we already knew it was going to break hundred of projects immediately.

In that scenario, "latest stopped meaning the latest version of the software itself" and started meaning something like "the lastest version of this software that keeps working on Read the Docs". This brought confusions to our users and problems to ourselves.

That said, if ubuntu-lts-latest will be pointed always to the latest version of the software and we will upgrade it even knowing that it will break people's projects, I'm 💯 on moving forward with that.

Latest and reproducible are opposites

This is a pretty good summary 💯

---

"reproducible by default, latest by choice" :D

The default versions is a more complex topic, in my opinion, that we can discuss in a specific issue. I agree that having build.image: latest with Python 3.7 as default currently is, at least, weird. In particular, now that 3.7 is close to reach EOL (ends in 7 months and 3 weeks (27 Jun 2023)); see https://endoflife.date/python

[benjaoming]

Good point - we should definitely document what the definition of latest is. And I think we can expect to do separate definitions. Example draft:

ubuntu-latest-lts: Use this setting to always run the latest Long Term Support (LTS) version of Ubuntu. Images are regularly updated with the latest package updates, but distribution bump from LTS to LTS comes with a significant delay to ensure stability. Using this setting comes at your own responsibility. If the version of Ubuntu changes, your builds might break, and then you will have to update your project. Current value: 22.04

[ericholscher]

Agreed on documenting what latest means. That snippet looks good. 👍

[avylove]

Wondering why this wasn't implemented before configuration files became required. As I've rolled out configuration files to projects, I cringe every time I have to write ubuntu-22.04 knowing I'm going to have to go back and change it down the road.

[ericholscher]

We've just shipped a version of this, so if you'd like to test it out, it should now be live. The version that latest will point to is the most recent in the docs: https://docs.readthedocs.io/en/stable/config-file/v2.html#build-tools-python