Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Config file: add support for latest aliases #11081

Merged
merged 7 commits into from
Feb 5, 2024
Merged

Config file: add support for latest aliases #11081

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
4b7e0be
Config file: add support for latest aliases
stsewd Jan 30, 2024
6d1a371
User variables to make it shorter
stsewd Jan 31, 2024
ffb77d8
Update OS
stsewd Jan 31, 2024
84f1c72
Updates from review
stsewd Jan 31, 2024
3fb8628
Rename ubuntu-latest-lts to ubuntu-lts-latest
stsewd Feb 1, 2024
1bfb494
Merge branch 'main' into add-latest-aliases
stsewd Feb 1, 2024
57e1b89
Add alias for ruby
stsewd Feb 1, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 30 additions & 2 deletions docs/user/config-file/v2.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
```````````

Expand All @@ -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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are we documenting what latest currently points to? Seems like that would be useful information, but also a pain to update.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Was hoping that (alias for the latest version available on Read the Docs) on each tag would be enough given the list of all available versions.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So it's basically the same as the first item in the list?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Last item


.. 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
``````````````````

Expand All @@ -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
``````````````````
Expand All @@ -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
````````````````
Expand All @@ -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
````````````````
Expand All @@ -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
``````````````````
Expand All @@ -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
``````````````````
Expand Down
35 changes: 23 additions & 12 deletions readthedocs/builds/constants_docker.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
stsewd marked this conversation as resolved.
Show resolved Hide resolved
# - 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": {
Expand All @@ -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",
Expand Down Expand Up @@ -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"]
25 changes: 20 additions & 5 deletions readthedocs/rtd_tests/fixtures/spec/v2/schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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": {
Expand Down Expand Up @@ -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": {
Expand All @@ -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"
]
}
},
Expand Down