Deprecation plan for stable, testing, and latest images

[agjohnson]

We keep hitting issues with these images and we are not confident in updating them anymore, so we should start to discuss full deprecation so we're not stuck in limbo, between active maintenance and full deprecation. For some context, 70% of builds are using the latest image. This makes the problem harder, as now our least maintained image is the most used.

Our new images are much nicer to use, and most users should be able to upgrade. However, this is probably something we want make the responsibility of the project maintainers. At least to start. At some point we probably want to throw errors on builds when the image is in use.

We could also take latest to mean "just use whatever is newer" and try ubuntu-22.04 for the build.

Plan

TBD

[agjohnson]

One option could be:

• We set a cutover date
• We notify users using latest of the upcoming deprecation
• Users should try a new build image manually before that date
• We might want to do something automated too? Like give the maintainers a configuration file to use
• After the cutoff date, we tag readthedocs/build:ubuntu-22.04 as readthedocs/build:latest
• Same for stable/testing?

Maybe a brownout of sorts somewhere in there?

Do we have to worry about Python versions at all? I suppose we might have some Python versions available on the old images that were deprecated in the new images

[humitos]

We could also take latest to mean "just use whatever is newer" and try ubuntu-22.04 for the build.

This is not 100% possible because build.os requires build.tools.* since none of the Ubuntu image have any Python version by default. Besides, I think it's not a good idea to re-use an old config value to mean something completely different now.

Also, I want users to be explicit about what they want to use to avoid reaching a similar state where we are now with latest being pretty old and also defaulting to Python 3.7 because we weren't able to upgrade without breaking lot of projects.

We can follow the idea of using build.os: ubuntu-latest proposed in readthedocs/readthedocs.org#8861

[humitos]

Just a bunch of related issues so we can easily find them:

• https://github.com/readthedocs/meta/discussions/68
• https://github.com/readthedocs/meta/discussions/48
• Support some form of "latest" for build.os readthedocs.org#8861
• Increase default python version to 3.8 or higher readthedocs.org#9623

[agjohnson]

This is not 100% possible because build.os requires build.tools.* since none of the Ubuntu image have any Python version by default.

It seems like what we do need is the template UI and lots of communication then. If we're unwilling to provide users with some default build.tools, we need every project to upgrade to the new pattern before we can enforce it.

A couple notes for our deprecation plan:

• We talked about setting a pair of dates, one for a public cutoff and one for a hard cutoff.
  • The public cutoff would be when we advertise users need to change their configuration by. We aggressively communicate this to users still lingering. We don't actually make changes yet that would fail builds though.
  • The hard cutoff is when we start failing builds. We'll have more communication to manage depending on how many projects haven't made changes yet.
• We should set targets for some of our dates, like 50% of non-spam projects have moved by our brownout test date, 80% of projects by public cutoff, 95% of projects by hard cutoff. These are arbitrary, but just a metric we for us to check in on.
  • If we're significantly behind, we would alter our plan slightly -- push out dates, increase communication, etc.

[humitos]

I had in mind that our migration to a configuration file will automatically deprecate these images. However, that's not 100% true and we will need to deal with a specific plan for deprecating these ones. This is because people already using a configuration file v2 with build.image won't get any notification and are not forced to migrate.

We have 1.6k projects with a build in the last 180 days manually specifying build.image. This is not a huge number and looks more manageable. However, I think the plan would be similar to our current one for the config file: blog post, onsite and email notification weekly.

Besides, even people that migrate from no-config file to a config file are allowed to use build.image, since we are not failing those builds. I doubt they are going to do that, tho, but they could.

[humitos]

We have 1.6k projects with a build in the last 180 days manually specifying build.image. This is not a huge number and looks more manageable. However, I think the plan would be similar to our current one for the config file: blog post, onsite and email notification weekly.

I re-executed this query using 90 days: https://ethicalads.metabaseapp.com/question/405-projects-specifying-build-image-config-file?days=90 and we have 1k projects specifying build.image currently

[humitos]

There is an ongoing notification sent weekly and it's planned to drop support on October 16th. I'm closing this issue because there is nothing else to do here.