From cdc03fdec8e65934f2fd00a603445e5ad4d324a5 Mon Sep 17 00:00:00 2001 From: "Tomoya.Fujita" Date: Mon, 27 Jul 2026 10:07:54 +0900 Subject: [PATCH 1/2] Stop building & deploying EOL distro documentation. Signed-off-by: Tomoya.Fujita --- conf.py | 74 +++++++++++++++++-- .../Creating-or-updating-documentation.rst | 3 +- source/_templates/versions.html | 9 +++ 3 files changed, 77 insertions(+), 9 deletions(-) diff --git a/conf.py b/conf.py index c6aee806cb8..8b0d04f8b7d 100644 --- a/conf.py +++ b/conf.py @@ -134,14 +134,8 @@ # smv_tag_whitelist = None -smv_branch_whitelist = r'^(rolling|lyrical|kilted|jazzy|iron|humble|galactic|foxy|eloquent|dashing|crystal)$' - - -smv_released_pattern = r'^refs/(heads|remotes/[^/]+)/(lyrical|kilted|jazzy|iron|humble|galactic|foxy|eloquent|dashing|crystal).*$' -smv_remote_whitelist = r'^(origin)$' -smv_latest_version = 'lyrical' -smv_eol_versions = ['crystal', 'dashing', 'eloquent', 'foxy', 'galactic', 'iron'] - +# All ROS 2 distributions, in release order. This dict is the single source of +# truth for the set and ordering of distros used throughout this file. distro_full_names = { 'crystal': 'Crystal Clemmys', 'dashing': 'Dashing Diademata', @@ -156,6 +150,62 @@ 'rolling': 'Rolling Ridley', } +# Every distro that has a documentation branch, in release order (dict preserves +# insertion order). +smv_all_versions = list(distro_full_names) + +smv_latest_version = 'lyrical' + +# Distributions that have reached end-of-life (EOL). Being EOL is purely +# presentational: it drives the "(EOL)" label in the version menu and the banner +# stamped onto the distro's pages (see the eol_versions uses below). An EOL +# distro is *still built*, so that it receives one final "clean freeze" build +# that stamps those EOL markers into its published pages. +smv_eol_versions = ['crystal', 'dashing', 'eloquent', 'foxy', 'galactic', 'iron'] + +# Distributions whose documentation is frozen: dropped from the build set so the +# branch is no longer rebuilt, while its already-published (and EOL-stamped) docs +# stay served on docs.ros.org. Freezing prevents a warning in a frozen branch +# from being promoted to an error and breaking the whole multiversion build (and +# thus blocking deployment of the active distros). +# See https://github.com/ros2/ros2_documentation/issues/6964 +# +# A distro must be built at least once while EOL before it is frozen, so the +# freeze workflow is: add to smv_eol_versions -> one nightly build stamps the +# EOL banner/label -> verify -> add to smv_frozen_versions. Freezing must +# therefore only ever be a subset of EOL (asserted below). +smv_frozen_versions = ['crystal', 'dashing', 'eloquent', 'foxy', 'galactic', 'iron'] + +# Only build branches for distros that are not frozen. Derived so that freezing a +# distro (adding it to smv_frozen_versions) automatically stops it from being +# rebuilt. +smv_active_versions = [v for v in smv_all_versions if v not in smv_frozen_versions] +smv_branch_whitelist = r'^(' + '|'.join(smv_active_versions) + r')$' + +# Frozen distros in version-menu display order (newest first). +smv_frozen_versions_ordered = [ + v for v in reversed(smv_all_versions) if v in smv_frozen_versions +] + +# Everything except the development branch (rolling) is a released version. +smv_released_versions = [v for v in smv_all_versions if v != 'rolling'] +smv_released_pattern = ( + r'^refs/(heads|remotes/[^/]+)/(' + + '|'.join(smv_released_versions) + + r').*$' +) +smv_remote_whitelist = r'^(origin)$' + +# Fail the build loudly if the lists above are inconsistent, rather than +# silently dropping the latest distro (or the whole site) from the build set. +assert set(smv_frozen_versions) <= set(smv_eol_versions), \ + 'smv_frozen_versions must be a subset of smv_eol_versions' +assert smv_active_versions, 'smv_active_versions must not be empty' +assert smv_latest_version in smv_active_versions, \ + 'smv_latest_version must be an actively built (non-frozen) distro' +assert 'rolling' in smv_active_versions, \ + 'the rolling development branch must always be built' + # Tier 1 Ubuntu platform for binary deb installs (see the release page for each distro) distro_ubuntu_deb_platform = { 'crystal': 'Ubuntu Bionic (18.04)', @@ -360,6 +410,14 @@ def github_link_rewrite_branch(app, pagename, templatename, context, doctree): if app.config.smv_current_version != '': context['github_version'] = app.config.smv_current_version + '/source/' context['eol_versions'] = app.config.smv_eol_versions + # Frozen distros are no longer rebuilt, so sphinx-multiversion does not + # add them to the version menu. Provide the list (newest first) and the + # base URL of their published docs so the menu can still link to them. + # Use the module-level html_baseurl, which is the un-rewritten base + # ('https://docs.ros.org/en'); app.config.html_baseurl has by now been + # rewritten per-version by smv_rewrite_configs. + context['frozen_versions'] = smv_frozen_versions_ordered + context['frozen_base_url'] = html_baseurl def expand_macros(app, docname, source): result = source[0] diff --git a/source/The-ROS2-Project/Contributing/Documentation/Creating-or-updating-documentation.rst b/source/The-ROS2-Project/Contributing/Documentation/Creating-or-updating-documentation.rst index ad52144056c..39d354a9487 100644 --- a/source/The-ROS2-Project/Contributing/Documentation/Creating-or-updating-documentation.rst +++ b/source/The-ROS2-Project/Contributing/Documentation/Creating-or-updating-documentation.rst @@ -243,7 +243,8 @@ This has two drawbacks: To show local changes in the multiversion output: #. Commit the changes to a local branch. -#. Edit the `conf.py `_ file and change the ``smv_branch_whitelist`` variable to point to your branch. +#. Edit the `conf.py `_ file so that the ``smv_branch_whitelist`` variable points to your branch. + Note that ``smv_branch_whitelist`` is now derived from ``smv_active_versions`` (the distros that are not frozen), so for a local test build the simplest change is to override it directly, for example ``smv_branch_whitelist = r'^my-branch$'``. Using the live server ^^^^^^^^^^^^^^^^^^^^^ diff --git a/source/_templates/versions.html b/source/_templates/versions.html index f5f80e8920c..656fe29d8a2 100644 --- a/source/_templates/versions.html +++ b/source/_templates/versions.html @@ -17,6 +17,15 @@
{{ item.name|title }}
{%- endif %} {%- endfor %} + {#- Frozen distros are no longer built, so they are absent from + versions.releases (an EOL-but-not-yet-frozen distro is still built and + is handled by the (EOL) branch above). List the frozen ones here, + already in newest-first order, linking to their published docs. #} + {%- if frozen_base_url %} + {%- for name in frozen_versions %} +
{{ name|title }} (EOL)
+ {%- endfor %} + {%- endif %}
In Development
From ce694eba92cc9883e67c5366e1728aa338b7127a Mon Sep 17 00:00:00 2001 From: Tomoya Fujita Date: Thu, 6 Aug 2026 10:31:22 +0900 Subject: [PATCH 2/2] add EOL and freezing its documentation. Signed-off-by: Tomoya Fujita --- conf.py | 5 ++- .../Creating-or-updating-documentation.rst | 39 +++++++++++++++++++ 2 files changed, 43 insertions(+), 1 deletion(-) diff --git a/conf.py b/conf.py index 8b0d04f8b7d..f16ec2b831b 100644 --- a/conf.py +++ b/conf.py @@ -173,7 +173,10 @@ # A distro must be built at least once while EOL before it is frozen, so the # freeze workflow is: add to smv_eol_versions -> one nightly build stamps the # EOL banner/label -> verify -> add to smv_frozen_versions. Freezing must -# therefore only ever be a subset of EOL (asserted below). +# therefore only ever be a subset of EOL (asserted below). The full procedure is +# documented in source/The-ROS2-Project/Contributing/Documentation/ +# Creating-or-updating-documentation.rst ("Marking a distribution EOL and +# freezing its documentation"). smv_frozen_versions = ['crystal', 'dashing', 'eloquent', 'foxy', 'galactic', 'iron'] # Only build branches for distros that are not frozen. Derived so that freezing a diff --git a/source/The-ROS2-Project/Contributing/Documentation/Creating-or-updating-documentation.rst b/source/The-ROS2-Project/Contributing/Documentation/Creating-or-updating-documentation.rst index 39d354a9487..47d5b3e88ec 100644 --- a/source/The-ROS2-Project/Contributing/Documentation/Creating-or-updating-documentation.rst +++ b/source/The-ROS2-Project/Contributing/Documentation/Creating-or-updating-documentation.rst @@ -356,3 +356,42 @@ Making a PR ^^^^^^^^^^^ When you've finished your documentation changes, submit them by :ref:`making a pull request `. + +Marking a distribution EOL and freezing its documentation +---------------------------------------------------------- + +.. note:: + + This is a maintainer task. + Regular contributors do not need to follow this section. + +Each distribution's documentation goes through three stages: + +#. **Active**: the distribution branch is rebuilt by every documentation build and its pages carry no special markings. +#. **EOL**: the distribution has reached its end-of-life date (see `REP 2000 `__), and its pages are stamped with an EOL banner and an ``(EOL)`` label in the version menu. + An EOL distribution is still rebuilt, so that one final build publishes those EOL markings. +#. **Frozen**: the distribution branch is dropped from the build set and is never rebuilt again. + Its already-published, EOL-stamped pages stay served on `docs.ros.org `__, and the version menu keeps linking to them. + +Freezing matters because the multiversion build promotes warnings to errors across all branches it builds. +A stale external link or a tooling change can make an old, unmaintained branch fail, which blocks deployment of every active distribution (see `issue #6964 `__). +Dropping EOL branches from the build set removes that risk. + +A distribution must be built at least once while marked EOL before it is frozen, otherwise its published pages would never receive the EOL banner. +This ordering is enforced by assertions in `conf.py `_: the frozen list must always be a subset of the EOL list. +The steps are therefore done in two separate pull requests: + +#. **Mark the distribution EOL.** + When the distribution reaches its end-of-life date, open a pull request against the ``rolling`` branch that adds the distribution to ``smv_eol_versions`` in ``conf.py``. + +#. **Verify the published EOL markings.** + After the pull request is merged, wait for the next nightly deployment and confirm on `docs.ros.org `__ that the distribution's pages show the EOL banner and that the version menu labels it ``(EOL)``. + +#. **Freeze the distribution.** + Open a second pull request against the ``rolling`` branch that adds the distribution to ``smv_frozen_versions`` in ``conf.py``. + The build set (``smv_active_versions``) and the version menu entries for frozen distributions are both derived from this list, so no other changes are needed. + Aim to complete the freeze within about a month of the end-of-life date: EOL documentation rarely changes, and every build that still includes the branch is a chance for it to break the whole site. + +After the freeze is merged, verify that the next nightly deployment still lists the distribution in the version menu (linking to its preserved pages) and that the multiversion build no longer checks out its branch. + +If documentation for a frozen distribution ever needs to be corrected, remove the distribution from ``smv_frozen_versions``, merge the fix into the distribution branch, let a build publish it, and then freeze it again.