diff --git a/docs/user/config-file/v2.rst b/docs/user/config-file/v2.rst index c3c5adfe919..a52cb86053e 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-lts-latest`` :Required: ``true`` +.. note:: + + 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-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 ``````````` @@ -286,6 +295,16 @@ Version specifiers for each tool. It must contain at least one tool. :Options: ``python``, ``nodejs``, ``ruby``, ``rust``, ``golang`` :Required: ``true`` +.. note:: + + Each tool has a ``latest`` option available, which refers to the latest version available on Read the Docs, + 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 newest version of the tool when it's updated by Read the Docs. + build.tools.python `````````````````` @@ -301,7 +320,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 +328,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 +347,7 @@ Node.js version to use. - ``18`` - ``19`` - ``20`` + - ``latest`` (alias for the latest version available on Read the Docs) build.tools.ruby ```````````````` @@ -334,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 ```````````````` @@ -346,6 +370,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 `````````````````` @@ -358,6 +384,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 c61c0112367..383400325bc 100644 --- a/readthedocs/builds/constants_docker.py +++ b/readthedocs/builds/constants_docker.py @@ -9,17 +9,17 @@ 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 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``. RTD_DOCKER_BUILD_SETTINGS = { # Mapping of build.os options to docker image. "os": { @@ -37,8 +37,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", @@ -69,3 +67,16 @@ }, }, } + +# Set latest aliases for OS and tools. +_OS = RTD_DOCKER_BUILD_SETTINGS["os"] +_TOOLS = RTD_DOCKER_BUILD_SETTINGS["tools"] +_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"] +_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 78a66b554e7..aec2a619b4b 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-lts-latest" ] }, "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,14 @@ "16", "18", "19", - "20" + "20", + "latest" + ] + }, + "ruby": { + "enum": [ + "3.3", + "latest" ] }, "rust": { @@ -169,7 +180,9 @@ "1.55", "1.61", "1.64", - "1.70" + "1.70", + "1.75", + "latest" ] }, "golang": { @@ -177,7 +190,9 @@ "1.17", "1.18", "1.19", - "1.20" + "1.20", + "1.21", + "latest" ] } },