Config file: add support for latest aliases (#11081)

* Config file: add support for latest aliases - Closes #8861 - Closes #10912 Ref readthedocs/meta#140 * User variables to make it shorter * Update OS * Updates from review * Rename ubuntu-latest-lts to ubuntu-lts-latest * Add alias for ruby
readthedocs · Feb 5, 2024 · 2063793 · 2063793
1 parent 74b4541
commit 2063793
Show file tree

Hide file tree

Showing 3 changed files with 73 additions and 19 deletions.
diff --git 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,17 +320,20 @@ 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``
   - ``3.9``
   - ``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
@@ -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 <tool>``)
-#
-# - 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 <tool>``).
+# - 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
@@ -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,23 +165,34 @@
                 "16",
                 "18",
                 "19",
-                "20"
+                "20",
+                "latest"
+              ]
+            },
+            "ruby": {
+              "enum": [
+                "3.3",
+                "latest"
               ]
             },
             "rust": {
               "enum": [
                 "1.55",
                 "1.61",
                 "1.64",
-                "1.70"
+                "1.70",
+                "1.75",
+                "latest"
               ]
             },
             "golang": {
               "enum": [
                 "1.17",
                 "1.18",
                 "1.19",
-                "1.20"
+                "1.20",
+                "1.21",
+                "latest"
               ]
             }
           },