docs

Author: irinascurtu

menu/menu.yaml

@@ -1092,6 +1092,8 @@
       Title: Transaction support
     - Url: transports/ibmmq/native-integration
       Title: Native integration
+    - Url: transports/ibmmq/observability
+      Title: Observability
     - Url: transports/ibmmq/operations-scripting
       Title: Scripting
   - Title: RabbitMQ

transports/ibmmq/topology.md

@@ -65,6 +65,18 @@ graph LR
 > [!NOTE]
 > For polymorphic subscriptions to work correctly, all concrete event types must be loadable in the subscribing endpoint's AppDomain. If a concrete type is defined in an assembly that is not referenced, the subscription for that type will not be created.
 
+### Recommendations for message hierarchies
+
+When using polymorphic events, distribute event types in dedicated, independently versioned packages. This allows subscribers to reference new concrete types and update their subscriptions before the publisher begins publishing those events.
+
+Ensure that the deployment pipeline runs all subscriber subscription steps **before** starting the new version of the publisher. If a publisher starts publishing a new concrete event type before subscribers have created their subscriptions, those messages will be lost because no durable subscription exists to route them to a queue.
+
+A typical deployment order:
+
+1. Deploy the updated message contracts package containing the new event type.
+2. Run the [command-line tool](operations-scripting.md) to create subscriptions for all subscribers, or deploy and start all subscribing endpoints so they create their durable subscriptions.
+3. Deploy and start the publishing endpoint.
+
 ## Topic naming
 
 Topics are named using a configurable strategy. The default uses a prefix (default: `DEV`) and the fully qualified type name: