[24451] Documented changes for Topic Profile Lookup

docs/rst/notes/forthcoming_version.rst

@@ -6,3 +6,19 @@
 Forthcoming Version
 ###################
 
+This release includes the following **new features**:
+
+* :ref:`XML Participant <user_manual_participants_xml>` now supports topic-name endpoint profile lookup:
+  when creating a :term:`DataWriter` or :term:`DataReader` for a topic, a loaded XML profile whose name
+  matches the topic name is automatically applied, giving users full control over QoS fields such as
+  history, memory policy and transport.
+  A specific profile can also be selected per topic via the new ``endpoint-profile-name`` tag.
+  A new optional ``endpoint-qos-mode`` participant tag controls whether YAML QoS overrides the matching
+  XML profile (``xml-overridable``, default) or the profile is applied verbatim (``xml-standalone``).
+  For more details, see :ref:`user_manual_participants_xml_topic_profiles`.
+
+This release includes the following **documentation updates**:
+
+* Document topic-name endpoint profile lookup for the :ref:`XML Participant <user_manual_participants_xml>`,
+  including QoS fields always enforced by the *DDS Router* regardless of the profile.
+* Add *Endpoint Profiles* section to the :ref:`user_manual_configuration` page.

docs/rst/spelling_wordlist.txt

@@ -43,6 +43,7 @@ Requiredness
 runtime
 scalable
 Tsan
+unregister
 utils
 validator
 Vulcanexus

docs/rst/user_manual/configuration.rst

@@ -90,6 +90,18 @@ Under the **optional** tag ``raw``, an XML configuration (with the same format a
     These QoS should be configured by the user explicitly.
     Check :ref:`user_manual_participants_xml_profiles`.
 
+Endpoint profiles
+-----------------
+
+Profiles named after a topic are automatically applied to :term:`DataWriter` and :term:`DataReader` endpoints
+when they are created for that topic by an :ref:`XML Participant <user_manual_participants_xml>`.
+A specific profile can also be selected per topic via the ``endpoint-profile-name`` tag, instead of relying
+on the topic name.
+By default, QoS fields explicitly set in the YAML configuration override the matching XML profile's values
+(``endpoint-qos-mode: xml-overridable``); this can be changed to ``xml-standalone`` on the participant so the
+XML profile is applied verbatim.
+For more details, see :ref:`user_manual_participants_xml_topic_profiles`.
+
 Topics Configuration
 ====================
 

docs/rst/user_manual/participants/xml.rst

@@ -74,6 +74,72 @@ Notice that not setting such QoS will not affect the correct functionality of th
       </participant>
 
 
+.. _user_manual_participants_xml_topic_profiles:
+
+Topic-name endpoint profile lookup
+-----------------------------------
+When the XML Participant creates a DataWriter or DataReader for a topic, it looks for a loaded XML ``data_writer``
+or ``data_reader`` profile to configure that endpoint.
+By default, the |ddsrouter| looks for a profile **whose name matches the topic name**.
+If a matching profile is found, the endpoint is configured using that profile's QoS, giving the user
+control over fields such as history, memory policy, transport, etc.
+If no matching profile exists, the endpoint falls back to default QoS with values derived from the YAML configuration.
+
+.. note::
+
+    Certain QoS are always enforced by the |ddsrouter| regardless of the XML profile:
+    deadline on DataWriters (set to minimum so it matches any reader),
+    ``autodispose_unregistered_instances`` on DataWriters (set to ``false`` to preserve dispose/unregister forwarding semantics),
+    and ``expects_inline_qos`` on DataReaders for keyed topics.
+
+The following example loads a profile named ``my_topic`` that will be automatically applied when creating
+endpoints for a topic of that name:
+
+.. code-block:: xml
+
+    <dds>
+        <profiles>
+            <data_writer profile_name="my_topic">
+                <historyMemoryPolicy>DYNAMIC</historyMemoryPolicy>
+            </data_writer>
+            <data_reader profile_name="my_topic">
+                <historyMemoryPolicy>DYNAMIC</historyMemoryPolicy>
+            </data_reader>
+        </profiles>
+    </dds>
+
+Selecting a profile explicitly
+"""""""""""""""""""""""""""""""
+
+Instead of relying on the topic name, a specific profile can be selected for a topic with the
+``endpoint-profile-name`` tag under that topic's QoS configuration.
+When set, the |ddsrouter| looks up the XML profile with that name instead of the topic name:
+
+.. code-block:: yaml
+
+    topics:
+      - name: "rt/chatter"
+        qos:
+          endpoint-profile-name: "my_reader_profile"
+
+Overriding profile QoS from the YAML configuration
+"""""""""""""""""""""""""""""""""""""""""""""""""""
+
+When a matching XML profile is applied, the QoS fields explicitly set by the user in the YAML
+configuration take precedence over the values in the XML profile.
+This behavior is controlled by the ``endpoint-qos-mode`` participant tag, which accepts two values:
+
+* ``xml-overridable`` *(default)*: the XML profile is applied first, and any QoS field explicitly set in
+  the YAML configuration overrides the corresponding value from the profile.
+* ``xml-standalone``: the XML profile is applied verbatim; YAML QoS does not override it.
+
+.. code-block:: yaml
+
+    - name: xml_participant
+      kind: xml
+      endpoint-qos-mode: xml-standalone
+
+
 Repeater
 --------