docs: clarify auto-variadic socket input ordering in connect() (#11053)

Co-authored-by: Sebastian Husch Lee <10526848+sjrl@users.noreply.github.com>

Author: saivedant169

haystack/core/pipeline/base.py

@@ -446,6 +446,12 @@ def connect(self, sender: str, receiver: str) -> "PipelineBase":  # noqa: PLR091
         If connecting to a component that has several output connections, specify the inputs and output names as
         'component_name.connections_name'.
 
+        If multiple senders are connected to the same list-typed receiver socket, the socket is
+        promoted to a lazy variadic socket so it can accept all incoming values. With `Pipeline`,
+        the resulting list is ordered alphabetically by sender component name, not by the order in
+        which `connect()` was called. With `AsyncPipeline`, no ordering is guaranteed, since
+        components in different branches may run in parallel.
+
         :param sender:
             The component that delivers the value. This can be either just a component name or can be
             in the format `component_name.connection_name` if the component has multiple outputs.

releasenotes/notes/document-variadic-input-ordering-530d8feee4a1b900.yaml

@@ -0,0 +1,12 @@
+---
+enhancements:
+  - |
+    Document the input ordering behavior of auto-promoted lazy variadic sockets in
+    ``Pipeline.connect()``. When
+    multiple senders are connected to the same list-typed receiver socket, ordering
+    depends on the pipeline class. With ``Pipeline``, items are ordered alphabetically
+    by sender component name (because ``Pipeline.run()`` schedules components in
+    alphabetical order for deterministic execution), not by the order of ``connect()``
+    calls. With ``AsyncPipeline``, no ordering is guaranteed, since components in
+    different branches may run in parallel. The docstrings now point users to a
+    dedicated joiner component when they need explicit ordering.