Merge branch 'rolling' into contributing-to-ros2-documentation

keithkirkwood-3di · keithkirkwood-3di · commit 87d10182c117 · 2026-06-18T12:14:03.000+01:00
diff --git a/Makefile b/Makefile
@@ -9,6 +9,8 @@ ifeq ($(OS),Windows_NT)
 endif
 BUILD      = $(PYTHON) -m sphinx
 OPTS       =-c . -W # Treat warnings as errors
+LIVE_HOST  ?= 0.0.0.0
+LIVE_PORT  ?= 2022
 
 DICTIONARIES := codespell_dictionary.txt codespell_whitelist.txt
 
@@ -18,7 +20,7 @@ help:
 
 multiversion: Makefile
 	sphinx-multiversion $(OPTS) "$(SOURCE)" build/html
-	@echo "<html><head><meta http-equiv=\"refresh\" content=\"0; url=kilted/index.html\" /></head></html>" > build/html/index.html
+	@echo "<html><head><meta http-equiv=\"refresh\" content=\"0; url=lyrical/index.html\" /></head></html>" > build/html/index.html
 	$(PYTHON) make_sitemapindex.py
 
 %: Makefile
@@ -61,4 +63,7 @@ linkcheck:
 	@echo
 	@echo "Check finished. Report is in $(LINKCHECKDIR)."
 
-.PHONY: help Makefile multiversion test test-tools linkcheck lint spellcheck check-dictionaries sort-dictionaries
+serve:
+	sphinx-autobuild --host $(LIVE_HOST) --port $(LIVE_PORT) -c . $(SOURCE) $(OUT)/html
+
+.PHONY: help Makefile multiversion test test-tools linkcheck serve lint spellcheck check-dictionaries sort-dictionaries
diff --git a/README.md b/README.md
@@ -51,6 +51,27 @@ For local testing of the current tree use:
 
 `sensible-browser build/html/index.html`
 
+### Live-reload local development
+
+To iterate on documentation without manually rebuilding and refreshing the browser, use [`sphinx-autobuild`](https://github.com/sphinx-doc/sphinx-autobuild).
+It watches the source files, rebuilds incrementally on save, and serves the result with automatic browser reload.
+
+`sphinx-autobuild` is installed as part of `requirements.txt`.
+Start the live server with:
+
+```
+make serve
+```
+
+Then open `http://localhost:2022` in a browser.
+
+The `serve` target binds to `0.0.0.0:2022` by default (a little ROS 2 vibe) so the server is reachable through devcontainer / port forwarding.
+Override the bind address or port if needed:
+
+```
+make serve LIVE_HOST=127.0.0.1 LIVE_PORT=8080
+```
+
 ### Spelling Check
 
 To check the spelling, use:
diff --git a/conf.py b/conf.py
@@ -143,9 +143,9 @@
 smv_branch_whitelist = r'^(rolling|lyrical|kilted|jazzy|iron|humble|galactic|foxy|eloquent|dashing|crystal)$'
 
 
-smv_released_pattern = r'^refs/(heads|remotes/[^/]+)/(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 = 'kilted'
+smv_latest_version = 'lyrical'
 smv_eol_versions = ['crystal', 'dashing', 'eloquent', 'foxy', 'galactic', 'iron']
 
 distro_full_names = {
diff --git a/requirements.txt b/requirements.txt
@@ -4,6 +4,7 @@ docutils
 pip
 pytest
 sphinx
+sphinx-autobuild
 sphinx-copybutton
 sphinx-lint
 sphinx-multiversion
diff --git a/source/Concepts/Basic/About-Command-Line-Tools.rst b/source/Concepts/Basic/About-Command-Line-Tools.rst
@@ -85,6 +85,23 @@ Different :doc:`ROS_DOMAIN_ID <../Intermediate/About-Domain-ID>` values will res
 
 You can run ``ros2 daemon --help`` for more options for interacting with the daemon, including commands to start, stop, or check the status of the daemon process.
 
+Running the Daemon in the Foreground
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For debugging purposes, it can be useful to run the ROS 2 daemon in the foreground so that its output is printed directly to stdout and stderr.
+This can be done using the ``_ros2_daemon`` command, which is the entry point for the daemon process itself:
+
+.. code-block:: console
+
+   $ _ros2_daemon --ros-domain-id 0 --rmw-implementation rmw_fastrtps_cpp
+
+This will start the daemon without daemonizing, allowing you to observe all discovery activity and XML-RPC requests in real time.
+Replace ``--ros-domain-id`` and ``--rmw-implementation`` values with those appropriate for your setup.
+
+.. note::
+
+   Make sure to stop any existing daemon instance (``ros2 daemon stop``) before starting one in the foreground to avoid port conflicts.
+
 Implementation
 --------------
 
diff --git a/source/How-To-Guides/Migrating-from-ROS1/Migrating-Launch-Files.rst b/source/How-To-Guides/Migrating-from-ROS1/Migrating-Launch-Files.rst
@@ -428,6 +428,9 @@ There are, however, some changes w.r.t. ROS 1:
   It looks at configurations defined either with ``arg`` or ``let`` tag.
 * ``eval`` and ``dirname`` substitutions require escape characters for string values, e.g. ``if="$(eval '\'$(var variable)\' == \'val1\'')"``.
   You can also use HTML escapes like ``&quot;`` .
+* Boolean predicates can also be expressed directly with the ``equals``, ``not-equals``, ``and``, ``or``, ``any``, and ``all`` substitutions.
+  For example, ``if="$(equals $(var variable) val1)"`` is equivalent to ``if="$(eval '\'$(var variable)\' == \'val1\'')"``.
+  See :ref:`Boolean substitutions <BooleanSubstitutions>` for details.
 * ``eval`` does not pass configurations ( ``arg`` ) as local Python variables.
   They have to be accessed via ``$(var name)``.
 * The argument of ``eval`` has to be a quoted string in ROS 2.
diff --git a/source/Installation/Alternatives/Ubuntu-Development-Setup.rst b/source/Installation/Alternatives/Ubuntu-Development-Setup.rst
@@ -91,7 +91,7 @@ Install colcon mixins
 
 .. code-block:: console
 
-   $ colcon mixin add default https://github.com/colcon/colcon-defaults/raw/master/index.yaml
+   $ colcon mixin add default https://github.com/colcon/colcon-mixin-repository/raw/master/index.yaml
    $ colcon mixin update default
 
 Build the code in the workspace
diff --git a/source/Installation/RMW-Implementations/DDS-Implementations/Working-with-GurumNetworks-GurumDDS.rst b/source/Installation/RMW-Implementations/DDS-Implementations/Working-with-GurumNetworks-GurumDDS.rst
@@ -18,6 +18,8 @@ Version Requirements (`see the README for details <https://github.com/ros2/rmw_g
 ROS 2 Distro      GurumDDS Version
 ================  ================
 rolling           ``>= 3.2.0``
+lyrical           ``>= 3.2.0``
+kilted            ``>= 3.2.0``
 jazzy             ``>= 3.2.0``
 humble            ``3.1.x``
 ================  ================
diff --git a/source/Installation/RMW-Implementations/DDS-Implementations/Working-with-RTI-Connext-DDS.rst b/source/Installation/RMW-Implementations/DDS-Implementations/Working-with-RTI-Connext-DDS.rst
@@ -19,6 +19,7 @@ Install RTI Connext DDS
   ROS 2 Distribution  Installed using apt  To Build from Source
   ==================  ===================  ====================
   rolling             n/a                  ``7.7.0``
+  lyrical             ``7.7.0``            ``7.7.0``
   kilted              ``7.3.0``            ``7.3.0``
   jazzy               ``6.0.1``            ``6.0.1``
   humble              ``6.0.1``            ``6.0.1``
diff --git a/source/Installation/Windows-Install-Binary.rst b/source/Installation/Windows-Install-Binary.rst
@@ -89,28 +89,35 @@ Install additional RMW implementations (optional)
 The default middleware that ROS 2 uses is ``Fast DDS``, but the middleware (RMW) can be replaced at runtime.
 See the :doc:`guide <../How-To-Guides/Working-with-multiple-RMW-implementations>` on how to work with multiple RMWs.
 
+Install Visual Studio Build Tools 2022 (optional)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To compile packages written in C++, install Visual Studio Build Tools 2022.
+During installation, select the "Desktop development with C++" workload to
+ensure the MSVC compiler and Windows SDK are available.
+Download from `here <https://visualstudio.microsoft.com/vs/older-downloads/#visual-studio-2022-and-other-products>`_.
+
+Run all commands in the "x64 Native Tools Command Prompt for VS 2022"
+(available from the Start Menu), which configures the required build environment.
+
+.. note::
+
+   The full Visual Studio IDE is not required.
 
 Setup environment
 -----------------
 
 In either the same Command Prompt terminal or a new one, you can source the ROS 2 environment
 
-Source the pixi environment
+Source the environment
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Source the pixi environment to set up dependencies:
+In every Command Prompt you open to setup the ROS 2 workspace, source the pixi environment and the ROS2 environment:
 
 .. code-block:: console
 
    $ cd C:\dev\{DISTRO}
-
-Source the ROS 2 environment
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-This is required in every Command Prompt you open to setup the ROS 2 workspace:
-
-.. code-block:: console
-
+   $ pixi shell
    $ call C:\dev\{DISTRO}\local_setup.bat
 
 If you do not have RTI Connext DDS installed on your computer, it is normal to receive a warning that it is missing.
diff --git a/source/Releases.rst b/source/Releases.rst
@@ -23,6 +23,7 @@ Rows in the table marked in blue are the currently supported distributions.
 .. toctree::
    :hidden:
 
+   Releases/Release-Lyrical-Luth
    Releases/Release-Kilted-Kaiju
    Releases/Release-Jazzy-Jalisco
    Releases/Release-Humble-Hawksbill
@@ -50,22 +51,27 @@ Rows in the table marked in blue are the currently supported distributions.
      /* Targeting the cells and rows for the background and plain text */
     .rst-content table.distros:not(.field-list) tr:nth-child(1) td,
     .rst-content table.distros tr:nth-child(2),
-    .rst-content table.distros tr:nth-child(4) {
+    .rst-content table.distros:not(.field-list) tr:nth-child(3) td,
+    .rst-content table.distros:not(.field-list) tr:nth-child(5) td {
       background-color: #22314E;
       color: white;
     }
 
     /* Targeting the links inside those specific rows to force them to be not-blue */
     .rst-content table.distros:not(.field-list) tr:nth-child(1) td a,
     .rst-content table.distros tr:nth-child(2) a,
-    .rst-content table.distros tr:nth-child(4) a {
+    .rst-content table.distros:not(.field-list) tr:nth-child(3) td a,
+    .rst-content table.distros:not(.field-list) tr:nth-child(3) td a {
       color: #B0B0B0 !important;
     }
    </style>
 
 .. |rolling| image:: Releases/rolling-small.png
    :alt: Rolling logo
 
+.. |lyrical| image:: Releases/lyrical-small.png
+   :alt: Lyrical logo
+
 .. |kilted| image:: Releases/kilted-small.png
    :alt: Kilted logo
 
@@ -109,6 +115,11 @@ Rows in the table marked in blue are the currently supported distributions.
      - Logo
      - EOL date
      - ROS Boss
+   * - :doc:`Lyrical Luth <Releases/Release-Lyrical-Luth>`
+     - May 22, 2026
+     - |lyrical|
+     - May 2031
+     - `Shane Loretz <https://github.com/sloretz>`_
    * - :doc:`Kilted Kaiju <Releases/Release-Kilted-Kaiju>`
      - May 23, 2025
      - |kilted|
@@ -201,10 +212,10 @@ There is a new ROS 2 distribution released yearly on May 23rd (`World Turtle Day
      - Release date
      - Logo
      - EOL date
-   * - :doc:`Lyrical Luth <Releases/Release-Lyrical-Luth>`
-     - May 2026
+   * - :doc:`Makoa Mata-mata <Releases/Release-Makoa-Mata-mata>`
+     - May 2027
      - TBD
-     - May 2031
+     - Dec 2028
 
 
 .. _rolling_distribution:
diff --git a/source/Releases/Development.rst b/source/Releases/Development.rst
@@ -6,4 +6,4 @@ Below is the ROS 2 distribution that is currently in development.
 .. toctree::
    :maxdepth: 1
 
-   Release-Lyrical-Luth
+   Release-Makoa-Mata-mata
diff --git a/source/Releases/Release-Kilted-Kaiju.rst b/source/Releases/Release-Kilted-Kaiju.rst
@@ -1,5 +1,3 @@
-.. _latest-release:
-
 .. _kilted-release:
 
 Kilted Kaiju (codename 'kilted'; May, 2025)
diff --git a/source/Releases/Release-Lyrical-Luth.rst b/source/Releases/Release-Lyrical-Luth.rst
@@ -1,4 +1,4 @@
-.. _upcoming-release:
+.. _latest-release:
 
 .. _lyrical-release:
 
@@ -786,3 +786,45 @@ All you need to do is specialize ``class_loader::InterfaceTraits<>`` in your plu
 
 
 For more information see `ros/class_loader#223 <https://github.com/ros/class_loader/pull/223>`_.
+
+Runtime tracing opt-out mechanism
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+`Removing the built-in tracing instrumentation from ROS 2 <https://github.com/ros2/ros2_tracing/blob/lyrical/README.md#removing-the-instrumentation>`_ or `excluding tracepoints from the instrumentation <https://github.com/ros2/ros2_tracing/blob/lyrical/README.md#excluding-tracepoints>`_ have so far been build-time options only.
+This is all enabled by default in the Linux binaries.
+
+To avoid loading the tracer at runtime (and therefore disable all instrumentation), set the ``TRACETOOLS_RUNTIME_DISABLE`` environment variable to ``1``:
+
+.. code-block:: console
+
+    $ export TRACETOOLS_RUNTIME_DISABLE=1
+    $ ros2 run tracetools status
+    Tracing disabled
+
+See `ros2/ros2_tracing#185 <https://github.com/ros2/ros2_tracing/pull/185>`_ for more info.
+
+Long-term tracing improvements
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Snapshot mode tracing
+"""""""""""""""""""""
+
+By default, tracing sessions write trace data continuously to disk.
+Tracing sessions using LTTng's `snapshot mode <https://lttng.org/docs/v2.13/#doc-tracing-session-mode>`_ store trace data in memory and only write to disk when a `snapshot is taken <https://lttng.org/docs/v2.13/#doc-taking-a-snapshot>`_.
+When memory buffers fill up, the oldest data is discarded, maintaining a rolling history whose size can be controlled by configuring sub-buffer size.
+This "flight recorder" mode is useful for capturing trace data only when something interesting occurs, avoiding continuous disk writes and thus lowering the runtime performance impact even more.
+
+`Snapshot mode tracing <https://github.com/ros2/ros2_tracing/tree/lyrical#tracing-in-snapshot-mode>`_ is available in ``ros2_tracing`` through the `ros2 trace command <https://github.com/ros2/ros2_tracing/tree/lyrical#trace-command-1>`_ and the the `Trace launch file action <https://github.com/ros2/ros2_tracing/tree/lyrical#launch-file-trace-action-1>`_.
+
+See `ros2/ros2_tracing#195 <https://github.com/ros2/ros2_tracing/pull/195>`_ and `ros2/ros2_tracing#206 <https://github.com/ros2/ros2_tracing/pull/206>`_ for more info.
+
+Dual session tracing
+""""""""""""""""""""
+
+`Dual session mode <https://github.com/ros2/ros2_tracing/tree/lyrical#dual-session-tracing>`_ solves the problem of losing initialization trace data by using two separate tracing sessions: one for initialization events in snapshot mode, and another normal tracing session for runtime events.
+This allows starting to actively record trace data at any point without losing initialization data.
+
+Use the ``Trace`` action with ``dual_session=True`` to start the initialization data session in snapshot mode.
+Then use the trace commands with ``--dual-session`` option to take a snapshot of the initialization session and start the runtime session.
+
+See `ros2/ros2_tracing#191 <https://github.com/ros2/ros2_tracing/pull/191>`_ and `ros2/ros2_tracing#196 <https://github.com/ros2/ros2_tracing/pull/196>`_ for more info.
diff --git a/source/Releases/Release-Makoa-Mata-mata.rst b/source/Releases/Release-Makoa-Mata-mata.rst
@@ -0,0 +1,24 @@
+.. _upcoming-release:
+
+.. _makoa-release:
+
+Makoa Mata-mata (codename ``makoa``; May, 2027)
+===============================================
+
+.. toctree::
+   :hidden:
+
+   makoa/release-timeline.rst
+   makoa/supported-platforms.rst
+
+*Makoa Mata-mata* is the thirtienth release of ROS 2.
+It is a regular release, and is supported until December 2028.
+
+* TODO - link installation docs
+* :doc:`makoa/release-timeline`
+* :doc:`makoa/supported-platforms`
+
+New Features in Makoa
+---------------------
+
+TODO
diff --git a/source/Releases/makoa/release-timeline.rst b/source/Releases/makoa/release-timeline.rst
@@ -0,0 +1,12 @@
+Makoa Mata-mata Release Timeline
+================================
+
+For progress on the development of Makoa Mata-mata, see `this project board <https://github.com/orgs/ros2/projects/80>`__.
+For the broad process followed by Makoa Mata-mata, see the :doc:`process description page <../Release-Process>`.
+
+**Friday May 21st, 2027** - General Availability
+    * Release announcement.
+    * ROS desktop packages source freeze is lifted and ``rosdistro`` is reopened for Makoa pull requests.
+
+**December, 2028** - End-of-life
+    * ROS Makoa will stop receiving updates - including security updates
diff --git a/source/Releases/makoa/supported-platforms.rst b/source/Releases/makoa/supported-platforms.rst
@@ -0,0 +1,23 @@
+Makoa Mata-mata Supported Platforms
+===================================
+
+ROS Makoa supports the following platforms according to :doc:`the platform support tiers <../../The-ROS2-Project/Platform-Support-Tiers>`:
+
+TODO
+
+Minimum Language Requirements
+-----------------------------
+
+TODO
+
+Dependency Requirements
+-----------------------
+
+TODO
+
+Middleware Implementation support
+---------------------------------
+
+The default middleware in ROS Makoa is **TODO**.
+
+TODO
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
diff --git a/source/Tutorials/Beginner-Client-Libraries/Colcon-Tutorial.rst b/source/Tutorials/Beginner-Client-Libraries/Colcon-Tutorial.rst
diff --git a/source/Tutorials/Intermediate/Launch/Using-Substitutions.rst b/source/Tutorials/Intermediate/Launch/Using-Substitutions.rst
diff --git a/source/Tutorials/Intermediate/Rosdep.rst b/source/Tutorials/Intermediate/Rosdep.rst
diff --git a/source/Tutorials/Intermediate/Tf2/Using-Stamped-Datatypes-With-Tf2-Ros-MessageFilter.rst b/source/Tutorials/Intermediate/Tf2/Using-Stamped-Datatypes-With-Tf2-Ros-MessageFilter.rst
