Stop building & deploying EOL distro documentation.

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,65 @@
     '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). 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
+# 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 +413,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]

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 <https://github.com/ros2/ros2_documentation/blob/rolling/conf.py>`_ file and change the ``smv_branch_whitelist`` variable to point to your branch.
+#. Edit the `conf.py <https://github.com/ros2/ros2_documentation/blob/rolling/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
 ^^^^^^^^^^^^^^^^^^^^^
@@ -355,3 +356,42 @@ Making a PR
 ^^^^^^^^^^^
 
 When you've finished your documentation changes, submit them by :ref:`making a pull request <DeveloperGuidePullRequests>`.
+
+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 <https://www.ros.org/reps/rep-2000.html>`__), 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 <https://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 <https://github.com/ros2/ros2_documentation/issues/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 <https://github.com/ros2/ros2_documentation/blob/rolling/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 <https://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.

source/_templates/versions.html

@@ -17,6 +17,15 @@
         <dd><a href="{{ item.url }}">{{ item.name|title }}</a></dd>
         {%- 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 %}
+        <dd><a href="{{ frozen_base_url }}/{{ name }}/">{{ name|title }} (EOL)</a></dd>
+      {%- endfor %}
+      {%- endif %}
     </dl>
     <dl>
       <dt>In Development</dt>