apply review suggestions #1

en/middleware/uorb.md

@@ -149,21 +149,19 @@ Message versioning was introduced to address the challenges of maintaining compa
 
 This versioning mechanism supports the [ROS 2 Message Translation Node](../ros2/px4_ros2_msg_translation_node.md), which enables seamless communication between PX4 and ROS 2 applications; when different versions of message definitions are in use, the ROS 2 translation node ensures that messages can be converted and exchanged correctly.
 
-Versioned messages are stored in the `msg/versioned/` directory, distinct from their non-versioned counterparts, which reside directly in the `msg/` directory.
+Versioned messages are stored in the `msg/versioned/` directory (distinct from their non-versioned counterparts, which reside directly in the `msg/` directory).
 Each versioned message definition includes an additional field: `uint32 MESSAGE_VERSION = X`, where `X` corresponds to the current version of the message.
 When a versioned message definition is modified, the version number should be incremented to reflect changes in its structure or semantics.
-Additionally, [message translations](../ros2/px4_ros2_msg_translation_node.md#updating-a-message) must also be updated for versioned messages.
+Additionally, [message translations](../ros2/px4_ros2_msg_translation_node.md#updating-a-message) must also be updated for versioned messages, in order to convert from the old version to the new structure.
 
 Versioned messages are designed to remain more stable over time compared to their non-versioned counterparts, as they are intended to be used across multiple releases of PX4 and external systems, ensuring greater compatibility over longer periods.
 
-For the full list of versioned and non-versioned messages, refer to the full [uORB Message Reference](../msg_docs/index.md).
+For the full list of versioned and non-versioned messages, refer to the [uORB Message Reference](../msg_docs/index.md).
 
 For more on PX4 and ROS 2 communication, refer to the page about the [PX4-ROS 2 Bridge](../ros/ros2_comm.md).
 
 ## Message/Field Deprecation {#deprecation}
 
-(TODO: Is this section still relevant? Not seeing any `# DEPRECATED: ...` fields or msgs in latest PX4)
-
 As there are external tools using uORB messages from log files, such as [Flight Review](https://github.com/PX4/flight_review), certain aspects need to be considered when updating existing messages:
 
 - Changing existing fields or messages that external tools rely on is generally acceptable if there are good reasons for the update.

en/releases/main.md

@@ -41,7 +41,7 @@ Please continue reading for [upgrade instructions](#upgrade-guide).
   Mission commands that may take some time to complete, such as those for controlling gimbals, winches, and grippers, will progress to the next item when either feedback is received or the timeout expires.
   This is often used to provide a minimum delay for hardware that does not provide completion feedback, so that it can reach the commanded state before the mission progresses.
   ([PX4-Autopilot#23960](https://github.com/PX4/PX4-Autopilot/pull/23960)).
-- **[uORB]** Introduce a version field for a subset of uORB messages ([PX4-Autopilot#23850](https://github.com/PX4/PX4-Autopilot/pull/23850))
+- **[uORB]** Introduce a [version field](../middleware/uorb.md#message-versioning) for a subset of uORB messages ([PX4-Autopilot#23850](https://github.com/PX4/PX4-Autopilot/pull/23850))
 
 ### Control
 
@@ -76,7 +76,7 @@ Please continue reading for [upgrade instructions](#upgrade-guide).
 
 ### uXRCE-DDS / ROS2
 
-- **[Feature]** ROS 2 Translation Node to translate PX4 messages from one defintion version to another dynamically ([PX4-Autopilot#24113](https://github.com/PX4/PX4-Autopilot/pull/24113))
+- **[Feature]** <Badge type="warning" text="Experimental"/> [ROS 2 Message Translation Node](../ros2/px4_ros2_msg_translation_node.md) to translate PX4 messages from one defintion version to another dynamically ([PX4-Autopilot#24113](https://github.com/PX4/PX4-Autopilot/pull/24113))
 
 ### MAVLink
 

en/ros2/px4_ros2_msg_translation_node.md

@@ -2,49 +2,54 @@
 
 <Badge type="tip" text="main (PX4 v1.16+)" /> <Badge type="warning" text="Experimental" />
 
-The message translation node allows to run applications that are compiled with one set of message versions against a PX4 with another set of message versions, without having to change either the application or the PX4 side.
+The message translation node allows ROS 2 applications that were compiled against different versions of the PX4 messages to interwork with newer versions of PX4, and vice versa, without having to change either the application or the PX4 side.
 
 Specifically for this to work, topic publication/subscription/service names contain a message version in the form of `<topic_name>_v<version>`.
 
-The translation node knows about all existing message versions, and dynamically monitors the publications, subscriptions and services, and then creates translations as needed.
+Specifically, the translation node knows about all message versions previously defined by PX4, and dynamically monitors the publications, subscriptions and services, translating them into the current versions expected by the application and PX4 as needed.
 
-## Installation and First Test
+## Installation
 
-Create a ROS 2 workspace in which to build the message translation node and its dependencies.
+1. Create a ROS 2 workspace in which to build the message translation node and its dependencies.
 
-```bash
-mkdir -p /path/to/ros_ws/src
-```
+   ```sh
+   mkdir -p /path/to/ros_ws/src
+   ```
 
-Run the following helper script, it will copy the message definitions and translation node to your ROS workspace directory.
+2. Run the following helper script to copy the message definitions and translation node into your ROS workspace directory.
 
-```bash
-cd /path/to/ros_ws
-/path/to/PX4-Autopilot/Tools/copy_to_ros_ws.sh .
-```
+   ```sh
+   cd /path/to/ros_ws
+   /path/to/PX4-Autopilot/Tools/copy_to_ros_ws.sh .
+   ```
 
-Build and source the workspace.
+3. Build and source the workspace.
 
-```bash
-colcon build
-source /path/to/ros_ws/install/setup.bash
-```
+   ```sh
+   colcon build
+   source /path/to/ros_ws/install/setup.bash
+   ```
+4. Finally, run the translation node.
 
-Finally, run the translation node. You should see an output similar to:
+   ```sh
+   ros2 run translation_node translation_node_bin
+   ```
 
-```bash
-ros2 run translation_node translation_node_bin
-[INFO] [1734525720.729530513] [translation_node]: Registered pub/sub topics and versions:
-[INFO] [1734525720.729594413] [translation_node]: Registered services and versions:
-```
+    You should see an output similar to:
+
+   ```sh
+   [INFO] [1734525720.729530513] [translation_node]: Registered pub/sub topics and versions:
+   [INFO] [1734525720.729594413] [translation_node]: Registered services and versions:
+   ```
 
 ## Updating a Message
 
 When changing a message, a new version needs to be added.
 
-The steps include:
+The steps are:
 
-- Copy the versioned message file (`.msg`/`.srv`) to `px4_msgs_old/msg/` (or `px4_msgs_old/srv/`) and add the current version to the file name.
+- Increment `MESSAGE_VERSION` in the current message definition (the one in `msg/versioned/`).
+  Make the other changes to message fields that prompted the version change.
   For example `msg/versioned/VehicleAttitude.msg` becomes `px4_msgs_old/msg/VehicleAttitudeV3.msg`.
   Update the existing translations that use the current topic version to the now old version.
   For example `px4_msgs::msg::VehicleAttitude` becomes `px4_msgs_old::msg::VehicleAttitudeV3`.
@@ -64,7 +69,7 @@ For the second last step and for topics, there are two options:
   Or for example when moving a field from one message to another, a single translation should be added with the two older message versions as input and the two newer versions as output.
   This way there is no information lost when translating forward or backward.
 
-::: info
+::: warning
 If a nested message definition changes, all messages including that message also require a version update.
 This is primarily important for services.
 :::
@@ -108,4 +113,4 @@ For translations with multiple input topics, the translation continues once all
 - Having both publishers and subscribers for two different versions of a topic is currently not handled by the translation node and would trigger infinite circular publications.
   This could be extended if required.
 
-Original document with requirements: https://docs.google.com/document/d/18_RxV1eEjt4haaa5QkFZAlIAJNv9w5HED2aUEiG7PVQ/edit?usp=sharing
+Original document with requirements: https://docs.google.com/document/d/18_RxV1eEjt4haaa5QkFZAlIAJNv9w5HED2aUEiG7PVQ/edit?usp=sharing

en/ros2/user_guide.md

@@ -34,7 +34,7 @@ The generator uses the uORB message definitions in the source tree: [PX4-Autopil
 ROS 2 applications need to be built in a workspace that has the _same_ message definitions that were used to create the uXRCE-DDS client module in the PX4 Firmware.
 You can include these by cloning the interface package [PX4/px4_msgs](https://github.com/PX4/px4_msgs) into your ROS 2 workspace (branches in the repo correspond to the messages for different PX4 releases).
 
-Starting from PX4 x.x.x in which [message versioning](../middleware/uorb.md#message-versioning) was introduced (TODO: specify PX4 version), ROS2 applications may use a different version of message definitions than those used to build PX4.
+Starting from PX4 v1.16 (main) in which [message versioning](../middleware/uorb.md#message-versioning) was introduced, ROS2 applications may use a different version of message definitions than those used to build PX4.
 This requires the [ROS 2 Message Translation Node](../ros2/px4_ros2_msg_translation_node.md) to be running to ensure that messages can be converted and exchanged correctly.
 
 Note that the micro XRCE-DDS _agent_ itself has no dependency on client-side code.