WIP: message versioning

en/middleware/uorb.md

@@ -141,10 +141,27 @@ Make sure not to mix `orb_advertise_multi` and `orb_advertise` for the same topi
 
 The full API is documented in [platforms/common/uORB/uORBManager.hpp](https://github.com/PX4/PX4-Autopilot/blob/main/platforms/common/uORB/uORBManager.hpp).
 
+## Message Versioning
 
+Starting from PX4 version x.x.x, message versioning was introduced to address the challenges of maintaining compatibility across systems where different versions of message definitions may be in use, such as between PX4 and external systems like ROS 2.
+
+Versioned messages are stored in the `msg/versioned/` directory, distinct from their to their non-versioned counterparts, which reside 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.
+
+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.
+
+This versioning mechanism supports the ROS 2 message translation system (TODO: add link), which enables seamless communication between PX4 and ROS 2 applications.
+When different versions of message definitions are in use, the translation system ensures that messages can be converted and exchanged correctly.
+
+For the full list of versioned and non-versioned messages, refer to the full [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}
 
+(Is any of this still relevant? Not seeing 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/ros2/user_guide.md

@@ -32,7 +32,10 @@ The subset of uORB messages that are generated into the client are listed in [PX
 The generator uses the uORB message definitions in the source tree: [PX4-Autopilot/msg](https://github.com/PX4/PX4-Autopilot/tree/main/msg) to create the code for sending ROS 2 messages.
 
 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).
+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). (Add message versioning comment)
+
+Starting from PX4 x.x.x 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.
+However this will require the ROS 2 translation node (TODO: add link) 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.
 It can be built from [source](https://github.com/eProsima/Micro-XRCE-DDS-Agent) either standalone or as part of a ROS build, or installed as a snap.