From 4b7e0be6e8486315ec34dce8f53c88358a089705 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Tue, 30 Jan 2024 18:34:08 -0500 Subject: [PATCH 1/6] Config file: add support for latest aliases - Closes https://github.com/readthedocs/readthedocs.org/issues/8861 - Closes https://github.com/readthedocs/readthedocs.org/issues/10912 Ref https://github.com/readthedocs/meta/discussions/140 --- docs/user/config-file/v2.rst | 30 ++++++++++++++++-- readthedocs/builds/constants_docker.py | 31 ++++++++++++------- .../rtd_tests/fixtures/spec/v2/schema.json | 19 +++++++++--- 3 files changed, 61 insertions(+), 19 deletions(-) diff --git a/docs/user/config-file/v2.rst b/docs/user/config-file/v2.rst index 61fb4859636..7bdd6481da8 100644 --- a/docs/user/config-file/v2.rst +++ b/docs/user/config-file/v2.rst @@ -274,9 +274,18 @@ Image names refer to the operating system Read the Docs uses to build them. Arbitrary Docker images are not supported. :Type: ``string`` -:Options: ``ubuntu-20.04``, ``ubuntu-22.04`` +:Options: ``ubuntu-20.04``, ``ubuntu-22.04``, ``ubuntu-latest-lts`` :Required: ``true`` +.. note:: + + The ``ubuntu-latest-lts`` option refers to the latest LTS version of Ubuntu available on Read the Docs, + not the latest LTS version available. + +.. warning:: + + Using ``ubuntu-latest-lts`` may break your builds unexpectedly if your project isn't compatible with the latest version when it's updated. + build.tools ``````````` @@ -286,6 +295,15 @@ Version specifiers for each tool. It must contain at least one tool. :Options: ``python``, ``nodejs``, ``rust``, ``golang`` :Required: ``true`` +.. note:: + + Each tool has a ``latest`` option available, which refers to the latest version available on Read the Docs, + not the latest version available. Versions are updated at least once every six months. + +.. warning:: + + Using ``latest`` may break your builds unexpectedly if your project isn't compatible with the latest version of the tool when it's updated. + build.tools.python `````````````````` @@ -301,7 +319,7 @@ You can use several interpreters and versions, from CPython, Miniconda, and Mamb :Type: ``string`` :Options: - ``2.7`` - - ``3`` (last stable CPython version) + - ``3`` (alias for the latest 3.x version available on Read the Docs) - ``3.6`` - ``3.7`` - ``3.8`` @@ -309,9 +327,12 @@ You can use several interpreters and versions, from CPython, Miniconda, and Mamb - ``3.10`` - ``3.11`` - ``3.12`` + - ``latest`` (alias for the latest version available on Read the Docs) - ``miniconda3-4.7`` + - ``miniconda-latest`` (alias for the latest version available on Read the Docs) - ``mambaforge-4.10`` - ``mambaforge-22.9`` + - ``mambaforge-latest`` (alias for the latest version available on Read the Docs) build.tools.nodejs `````````````````` @@ -325,6 +346,7 @@ Node.js version to use. - ``18`` - ``19`` - ``20`` + - ``latest`` (alias for the latest version available on Read the Docs) build.tools.rust ```````````````` @@ -337,6 +359,8 @@ Rust version to use. - ``1.61`` - ``1.64`` - ``1.70`` + - ``1.75`` + - ``latest`` (alias for the latest version available on Read the Docs) build.tools.golang `````````````````` @@ -349,6 +373,8 @@ Go version to use. - ``1.18`` - ``1.19`` - ``1.20`` + - ``1.21`` + - ``latest`` (alias for the latest version available on Read the Docs) build.apt_packages `````````````````` diff --git a/readthedocs/builds/constants_docker.py b/readthedocs/builds/constants_docker.py index 3d8e1bf638a..bef452c2ad1 100644 --- a/readthedocs/builds/constants_docker.py +++ b/readthedocs/builds/constants_docker.py @@ -9,17 +9,16 @@ DOCKER_DEFAULT_IMAGE = "readthedocs/build" -# Adding a new tool/version to this setting requires: +# When adding a new tool/version to this setting, you should: # -# - a mapping between the expected version in the config file, to the full -# version installed via asdf (found via ``asdf list all ``) -# -# - running the script ``./scripts/compile_version_upload.sh`` in -# development and production environments to compile and cache the new -# tool/version -# -# Note that when updating this options, you should also update the file: -# readthedocs/rtd_tests/fixtures/spec/v2/schema.json +# - Add a mapping between the expected version in the config file, to the full +# version installed via asdf (found via ``asdf list all ``). +# - Run the script ``./scripts/compile_version_upload.sh`` in +# development and production environments to compile and cache the new +# tool/version. +# - Update the latest aliases for OS and tools (below this setting). +# - Update readthedocs/rtd_tests/fixtures/spec/v2/schema.json. +# - Update the documentation in ``docs/user/config-file/v2.rst``. RTD_DOCKER_BUILD_SETTINGS = { # Mapping of build.os options to docker image. "os": { @@ -37,8 +36,6 @@ "3.10": "3.10.13", "3.11": "3.11.6", "3.12": "3.12.0", - # Always point to the latest stable release. - "3": "3.12.0", "miniconda3-4.7": "miniconda3-4.7.12", "mambaforge-4.10": "mambaforge-4.10.3-10", "mambaforge-22.9": "mambaforge-22.9.0-3", @@ -66,3 +63,13 @@ }, }, } + +# Set latest aliases for OS and tools. +RTD_DOCKER_BUILD_SETTINGS["os"]["ubuntu-latest-lts"] = RTD_DOCKER_BUILD_SETTINGS["os"]["ubuntu-20.04"] +RTD_DOCKER_BUILD_SETTINGS["tools"]["python"]["3"] = RTD_DOCKER_BUILD_SETTINGS["tools"]["python"]["3.12"] +RTD_DOCKER_BUILD_SETTINGS["tools"]["python"]["latest"] = RTD_DOCKER_BUILD_SETTINGS["tools"]["python"]["3"] +RTD_DOCKER_BUILD_SETTINGS["tools"]["python"]["miniconda-latest"] = RTD_DOCKER_BUILD_SETTINGS["tools"]["python"]["miniconda3-4.7"] +RTD_DOCKER_BUILD_SETTINGS["tools"]["python"]["mambaforge-latest"] = RTD_DOCKER_BUILD_SETTINGS["tools"]["python"]["mambaforge-22.9"] +RTD_DOCKER_BUILD_SETTINGS["tools"]["nodejs"]["latest"] = RTD_DOCKER_BUILD_SETTINGS["tools"]["nodejs"]["20"] +RTD_DOCKER_BUILD_SETTINGS["tools"]["rust"]["latest"] = RTD_DOCKER_BUILD_SETTINGS["tools"]["rust"]["1.75"] +RTD_DOCKER_BUILD_SETTINGS["tools"]["golang"]["latest"] = RTD_DOCKER_BUILD_SETTINGS["tools"]["golang"]["1.21"] diff --git a/readthedocs/rtd_tests/fixtures/spec/v2/schema.json b/readthedocs/rtd_tests/fixtures/spec/v2/schema.json index 78a66b554e7..a5115d1d507 100644 --- a/readthedocs/rtd_tests/fixtures/spec/v2/schema.json +++ b/readthedocs/rtd_tests/fixtures/spec/v2/schema.json @@ -60,7 +60,8 @@ "description": "Operating system to be used in the build.", "enum": [ "ubuntu-20.04", - "ubuntu-22.04" + "ubuntu-22.04", + "ubuntu-latest-lts" ] }, "jobs": { @@ -150,9 +151,12 @@ "3.10", "3.11", "3.12", + "latest", "miniconda3-4.7", + "miniconda-latest", "mambaforge-4.10", - "mambaforge-22.9" + "mambaforge-22.9", + "mambaforge-latest" ] }, "nodejs": { @@ -161,7 +165,8 @@ "16", "18", "19", - "20" + "20", + "latest" ] }, "rust": { @@ -169,7 +174,9 @@ "1.55", "1.61", "1.64", - "1.70" + "1.70", + "1.75", + "latest" ] }, "golang": { @@ -177,7 +184,9 @@ "1.17", "1.18", "1.19", - "1.20" + "1.20", + "1.21", + "latest" ] } }, From 6d1a371dd0faadae86d2809bdb00947abb78ffcc Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Tue, 30 Jan 2024 19:06:07 -0500 Subject: [PATCH 2/6] User variables to make it shorter --- readthedocs/builds/constants_docker.py | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/readthedocs/builds/constants_docker.py b/readthedocs/builds/constants_docker.py index bef452c2ad1..0f002496c52 100644 --- a/readthedocs/builds/constants_docker.py +++ b/readthedocs/builds/constants_docker.py @@ -65,11 +65,13 @@ } # Set latest aliases for OS and tools. -RTD_DOCKER_BUILD_SETTINGS["os"]["ubuntu-latest-lts"] = RTD_DOCKER_BUILD_SETTINGS["os"]["ubuntu-20.04"] -RTD_DOCKER_BUILD_SETTINGS["tools"]["python"]["3"] = RTD_DOCKER_BUILD_SETTINGS["tools"]["python"]["3.12"] -RTD_DOCKER_BUILD_SETTINGS["tools"]["python"]["latest"] = RTD_DOCKER_BUILD_SETTINGS["tools"]["python"]["3"] -RTD_DOCKER_BUILD_SETTINGS["tools"]["python"]["miniconda-latest"] = RTD_DOCKER_BUILD_SETTINGS["tools"]["python"]["miniconda3-4.7"] -RTD_DOCKER_BUILD_SETTINGS["tools"]["python"]["mambaforge-latest"] = RTD_DOCKER_BUILD_SETTINGS["tools"]["python"]["mambaforge-22.9"] -RTD_DOCKER_BUILD_SETTINGS["tools"]["nodejs"]["latest"] = RTD_DOCKER_BUILD_SETTINGS["tools"]["nodejs"]["20"] -RTD_DOCKER_BUILD_SETTINGS["tools"]["rust"]["latest"] = RTD_DOCKER_BUILD_SETTINGS["tools"]["rust"]["1.75"] -RTD_DOCKER_BUILD_SETTINGS["tools"]["golang"]["latest"] = RTD_DOCKER_BUILD_SETTINGS["tools"]["golang"]["1.21"] +_OS = RTD_DOCKER_BUILD_SETTINGS["os"] +_TOOLS = RTD_DOCKER_BUILD_SETTINGS["tools"] +_OS["ubuntu-latest-lts"] = _OS["ubuntu-20.04"] +_TOOLS["python"]["3"] = _TOOLS["python"]["3.12"] +_TOOLS["python"]["latest"] = _TOOLS["python"]["3"] +_TOOLS["python"]["miniconda-latest"] = _TOOLS["python"]["miniconda3-4.7"] +_TOOLS["python"]["mambaforge-latest"] = _TOOLS["python"]["mambaforge-22.9"] +_TOOLS["nodejs"]["latest"] = _TOOLS["nodejs"]["20"] +_TOOLS["rust"]["latest"] = _TOOLS["rust"]["1.75"] +_TOOLS["golang"]["latest"] = _TOOLS["golang"]["1.21"] From ffb77d8ec0c46eaeea8abb314588a09634a8294d Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Tue, 30 Jan 2024 19:15:12 -0500 Subject: [PATCH 3/6] Update OS --- readthedocs/builds/constants_docker.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/readthedocs/builds/constants_docker.py b/readthedocs/builds/constants_docker.py index 0f002496c52..36d1e212cb2 100644 --- a/readthedocs/builds/constants_docker.py +++ b/readthedocs/builds/constants_docker.py @@ -67,7 +67,7 @@ # Set latest aliases for OS and tools. _OS = RTD_DOCKER_BUILD_SETTINGS["os"] _TOOLS = RTD_DOCKER_BUILD_SETTINGS["tools"] -_OS["ubuntu-latest-lts"] = _OS["ubuntu-20.04"] +_OS["ubuntu-latest-lts"] = _OS["ubuntu-22.04"] _TOOLS["python"]["3"] = _TOOLS["python"]["3.12"] _TOOLS["python"]["latest"] = _TOOLS["python"]["3"] _TOOLS["python"]["miniconda-latest"] = _TOOLS["python"]["miniconda3-4.7"] From 84f1c7213cd3b7fff557d49d4cc9858fe3ef74ea Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Wed, 31 Jan 2024 12:50:34 -0500 Subject: [PATCH 4/6] Updates from review --- docs/user/config-file/v2.rst | 11 ++++++----- readthedocs/builds/constants_docker.py | 5 +++-- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/user/config-file/v2.rst b/docs/user/config-file/v2.rst index 7bdd6481da8..4345c5684ca 100644 --- a/docs/user/config-file/v2.rst +++ b/docs/user/config-file/v2.rst @@ -279,12 +279,12 @@ Image names refer to the operating system Read the Docs uses to build them. .. note:: - The ``ubuntu-latest-lts`` option refers to the latest LTS version of Ubuntu available on Read the Docs, - not the latest LTS version available. + The ``ubuntu-latest-lts`` option refers to the latest Ubuntu LTS version of Ubuntu available on Read the Docs, + which may not match the latest Ubuntu LTS officially released. .. warning:: - Using ``ubuntu-latest-lts`` may break your builds unexpectedly if your project isn't compatible with the latest version when it's updated. + Using ``ubuntu-latest-lts`` may break your builds unexpectedly if your project isn't compatible with the newest Ubuntu LTS version when it's updated by Read the Docs. build.tools ``````````` @@ -298,11 +298,12 @@ Version specifiers for each tool. It must contain at least one tool. .. note:: Each tool has a ``latest`` option available, which refers to the latest version available on Read the Docs, - not the latest version available. Versions are updated at least once every six months. + which may not match the latest version officially released. + Versions and the ``latest`` option are updated at least once every six months to keep up with the latest releases. .. warning:: - Using ``latest`` may break your builds unexpectedly if your project isn't compatible with the latest version of the tool when it's updated. + Using ``latest`` may break your builds unexpectedly if your project isn't compatible with the newest version of the tool when it's updated by Read the Docs. build.tools.python `````````````````` diff --git a/readthedocs/builds/constants_docker.py b/readthedocs/builds/constants_docker.py index 36d1e212cb2..28d6a738bee 100644 --- a/readthedocs/builds/constants_docker.py +++ b/readthedocs/builds/constants_docker.py @@ -14,8 +14,9 @@ # - Add a mapping between the expected version in the config file, to the full # version installed via asdf (found via ``asdf list all ``). # - Run the script ``./scripts/compile_version_upload.sh`` in -# development and production environments to compile and cache the new -# tool/version. +# development to compile and cache the new tool/version. +# - Update the CircleCI job on the ``readthedocs-docker-images`` repository with the new versions at +# https://github.com/rtfd/readthedocs-docker-images/blob/d2760526abdfe27001946614b749abf8011b7f90/.circleci/config.yml#L38-L44. # - Update the latest aliases for OS and tools (below this setting). # - Update readthedocs/rtd_tests/fixtures/spec/v2/schema.json. # - Update the documentation in ``docs/user/config-file/v2.rst``. From 3fb86284633f10bddff52d7c09eba6923ca70601 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Thu, 1 Feb 2024 12:31:15 -0500 Subject: [PATCH 5/6] Rename ubuntu-latest-lts to ubuntu-lts-latest --- docs/user/config-file/v2.rst | 6 +++--- readthedocs/builds/constants_docker.py | 2 +- readthedocs/rtd_tests/fixtures/spec/v2/schema.json | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/user/config-file/v2.rst b/docs/user/config-file/v2.rst index 4345c5684ca..7b536b2b2ce 100644 --- a/docs/user/config-file/v2.rst +++ b/docs/user/config-file/v2.rst @@ -274,17 +274,17 @@ Image names refer to the operating system Read the Docs uses to build them. Arbitrary Docker images are not supported. :Type: ``string`` -:Options: ``ubuntu-20.04``, ``ubuntu-22.04``, ``ubuntu-latest-lts`` +:Options: ``ubuntu-20.04``, ``ubuntu-22.04``, ``ubuntu-lts-latest`` :Required: ``true`` .. note:: - The ``ubuntu-latest-lts`` option refers to the latest Ubuntu LTS version of Ubuntu available on Read the Docs, + The ``ubuntu-lts-latest`` option refers to the latest Ubuntu LTS version of Ubuntu available on Read the Docs, which may not match the latest Ubuntu LTS officially released. .. warning:: - Using ``ubuntu-latest-lts`` may break your builds unexpectedly if your project isn't compatible with the newest Ubuntu LTS version when it's updated by Read the Docs. + Using ``ubuntu-lts-latest`` may break your builds unexpectedly if your project isn't compatible with the newest Ubuntu LTS version when it's updated by Read the Docs. build.tools ``````````` diff --git a/readthedocs/builds/constants_docker.py b/readthedocs/builds/constants_docker.py index 28d6a738bee..2439bb95def 100644 --- a/readthedocs/builds/constants_docker.py +++ b/readthedocs/builds/constants_docker.py @@ -68,7 +68,7 @@ # Set latest aliases for OS and tools. _OS = RTD_DOCKER_BUILD_SETTINGS["os"] _TOOLS = RTD_DOCKER_BUILD_SETTINGS["tools"] -_OS["ubuntu-latest-lts"] = _OS["ubuntu-22.04"] +_OS["ubuntu-lts-latest"] = _OS["ubuntu-22.04"] _TOOLS["python"]["3"] = _TOOLS["python"]["3.12"] _TOOLS["python"]["latest"] = _TOOLS["python"]["3"] _TOOLS["python"]["miniconda-latest"] = _TOOLS["python"]["miniconda3-4.7"] diff --git a/readthedocs/rtd_tests/fixtures/spec/v2/schema.json b/readthedocs/rtd_tests/fixtures/spec/v2/schema.json index a5115d1d507..969c51ab3cd 100644 --- a/readthedocs/rtd_tests/fixtures/spec/v2/schema.json +++ b/readthedocs/rtd_tests/fixtures/spec/v2/schema.json @@ -61,7 +61,7 @@ "enum": [ "ubuntu-20.04", "ubuntu-22.04", - "ubuntu-latest-lts" + "ubuntu-lts-latest" ] }, "jobs": { From 57e1b89d2d4c74898cb7c2b65889385ea1c877f2 Mon Sep 17 00:00:00 2001 From: Santos Gallegos Date: Thu, 1 Feb 2024 12:36:58 -0500 Subject: [PATCH 6/6] Add alias for ruby --- docs/user/config-file/v2.rst | 1 + readthedocs/builds/constants_docker.py | 1 + readthedocs/rtd_tests/fixtures/spec/v2/schema.json | 6 ++++++ 3 files changed, 8 insertions(+) diff --git a/docs/user/config-file/v2.rst b/docs/user/config-file/v2.rst index b06977f2323..a52cb86053e 100644 --- a/docs/user/config-file/v2.rst +++ b/docs/user/config-file/v2.rst @@ -357,6 +357,7 @@ Ruby version to use. :Type: ``string`` :Options: - ``3.3`` + - ``latest`` (alias for the latest version available on Read the Docs) build.tools.rust ```````````````` diff --git a/readthedocs/builds/constants_docker.py b/readthedocs/builds/constants_docker.py index cb199186b2e..383400325bc 100644 --- a/readthedocs/builds/constants_docker.py +++ b/readthedocs/builds/constants_docker.py @@ -77,5 +77,6 @@ _TOOLS["python"]["miniconda-latest"] = _TOOLS["python"]["miniconda3-4.7"] _TOOLS["python"]["mambaforge-latest"] = _TOOLS["python"]["mambaforge-22.9"] _TOOLS["nodejs"]["latest"] = _TOOLS["nodejs"]["20"] +_TOOLS["ruby"]["latest"] = _TOOLS["ruby"]["3.3"] _TOOLS["rust"]["latest"] = _TOOLS["rust"]["1.75"] _TOOLS["golang"]["latest"] = _TOOLS["golang"]["1.21"] diff --git a/readthedocs/rtd_tests/fixtures/spec/v2/schema.json b/readthedocs/rtd_tests/fixtures/spec/v2/schema.json index 969c51ab3cd..aec2a619b4b 100644 --- a/readthedocs/rtd_tests/fixtures/spec/v2/schema.json +++ b/readthedocs/rtd_tests/fixtures/spec/v2/schema.json @@ -169,6 +169,12 @@ "latest" ] }, + "ruby": { + "enum": [ + "3.3", + "latest" + ] + }, "rust": { "enum": [ "1.55",