Config file: add support for latest aliases

- Closes #8861 - Closes #10912 Ref readthedocs/meta#140
readthedocs · Jan 30, 2024 · 4b7e0be · 4b7e0be
1 parent 505ee4c
commit 4b7e0be
Show file tree

Hide file tree

Showing 3 changed files with 61 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-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,17 +319,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 +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
@@ -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 <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 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
@@ -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,23 +165,28 @@
                 "16",
                 "18",
                 "19",
-                "20"
+                "20",
+                "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"
               ]
             }
           },