Say dag_bundle_name is only needed for two coordinators of one class

Reword the docs so dag_bundle_name reads as optional with one coordinator
per class, and needed when one class is configured more than once.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: 2 people

airflow-core/docs/authoring-and-scheduling/language-sdks/go.rst

@@ -207,8 +207,10 @@ then register the coordinator and route the queue to it in ``airflow.cfg`` (or t
     }
     queue_to_coordinator = {"golang": "go"}
 
-``dag_bundle_name`` names the Dag bundle the coordinator scans for executable bundles. Omit it to ship the
-executable bundles in the same Dag bundle as the Python stub Dag. ``queue_to_coordinator``
+``dag_bundle_name`` is optional. Omit it and the coordinator finds executable bundles in the task's own Dag
+bundle, the one that holds the Python stub Dag. Set it, as here, to keep them in a separate Dag bundle, for
+example when you configure more than one ``ExecutableCoordinator`` and each has its own bundles.
+``queue_to_coordinator``
 routes stub tasks with ``queue="golang"`` to this Go coordinator. See :ref:`go-sdk/coordinator-config` for
 the full list of accepted ``kwargs``.
 
@@ -534,11 +536,11 @@ All ``kwargs`` in the ``coordinators`` config entry are passed to the
 
   **Locating bundles.** Executable bundles always live in a Dag bundle:
 
-  * Set ``dag_bundle_name`` to load bundles from a configured Dag bundle, so they are delivered
-    and versioned through the same bundle machinery as your Dags. The task uses the version that
+  * Leave ``dag_bundle_name`` unset (the default) to load bundles from the **task's own** Dag bundle,
+    pinned to the version the run was created with.
+  * Set ``dag_bundle_name`` to keep bundles in a separate Dag bundle, for example one per
+    ``ExecutableCoordinator`` when you configure more than one. The task uses the version that Dag
     bundle is on when it starts, pinned for the whole task.
-  * Leave it unset (the default) to load bundles from the **task's own** Dag bundle, pinned
-    to the version the run was created with.
 
 .. _go-sdk/limitations:
 

airflow-core/docs/authoring-and-scheduling/language-sdks/java.rst

@@ -274,8 +274,10 @@ Configure Airflow so the parent JAR directory is a Dag bundle, the coordinator s
     }
     queue_to_coordinator = {"java": "java"}
 
-``dag_bundle_name`` names the Dag bundle that holds the JARs. You can instead omit it and ship the JARs in
-the same Dag bundle as ``sales_pipeline.py``.
+``dag_bundle_name`` is only needed when you configure more than one ``JavaCoordinator``. Each one must then
+name its own Dag bundle, otherwise the Dag importer cannot tell which coordinator should parse a JAR. With a
+single ``JavaCoordinator``, as here, it is optional: omit it and the coordinator finds the JARs in the task's
+own Dag bundle, the one that holds ``sales_pipeline.py``.
 
 ``java`` is a user-chosen coordinator name, not a reserved value. The value assigned to the queue in
 ``queue_to_coordinator`` must match a key in ``coordinators``.
@@ -1063,7 +1065,8 @@ All ``kwargs`` in the ``coordinators`` config entry are passed to the
    * - ``dag_bundle_name``
      - *(auto: task's own bundle)*
      - Name of a configured Dag bundle to load JARs from. It must name a bundle in
-       ``[dag_processor] dag_bundle_config_list``.
+       ``[dag_processor] dag_bundle_config_list``. Only needed when more than one
+       ``JavaCoordinator`` is configured.
    * - ``java_executable``
      - ``"java"``
      - Path to the ``java`` binary.  Defaults to ``java`` on ``$PATH``.
@@ -1084,11 +1087,11 @@ All ``kwargs`` in the ``coordinators`` config entry are passed to the
 
   **Locating JARs.** JARs always live in a Dag bundle:
 
-  * Set ``dag_bundle_name`` to load JARs from a configured Dag bundle, so they are delivered and
-    versioned through the same bundle machinery as your Dags. The task uses the version that bundle
-    is on when it starts, pinned for the whole task.
-  * Leave it unset (the default) to load JARs from the **task's own** Dag bundle, pinned to
-    the version the run was created with.
+  * Leave ``dag_bundle_name`` unset (the default) to load JARs from the **task's own** Dag bundle, pinned
+    to the version the run was created with. This is all you need with a single ``JavaCoordinator``.
+  * With more than one ``JavaCoordinator``, set ``dag_bundle_name`` on each to a different Dag bundle, so
+    the Dag importer can tell which coordinator parses which JAR. The task uses the version that bundle is
+    on when it starts, pinned for the whole task.
 
 .. note::
 

airflow-core/docs/authoring-and-scheduling/language-sdks/typescript.rst

@@ -238,8 +238,10 @@ variables):
     }
     queue_to_coordinator = {"typescript": "ts"}
 
-``dag_bundle_name`` names the Dag bundle the coordinator scans for ``*.min.mjs`` bundles. Omit it to ship the
-bundles in the same Dag bundle as the Python stub Dag. ``queue_to_coordinator`` routes stub tasks with
+``dag_bundle_name`` is only needed when you configure more than one ``NodeCoordinator``. Each one must then
+name its own Dag bundle, otherwise the Dag importer cannot tell which coordinator should parse a ``*.min.mjs``
+bundle. With a single ``NodeCoordinator``, as here, it is optional: omit it and the coordinator finds the
+bundles in the task's own Dag bundle, the one that holds the Python stub Dag. ``queue_to_coordinator`` routes stub tasks with
 ``queue="typescript"`` to this coordinator. See :ref:`typescript-sdk/coordinator-config` for the full list
 of accepted ``kwargs``.
 
@@ -548,7 +550,8 @@ All ``kwargs`` in the ``coordinators`` config entry are passed to the
    * - ``dag_bundle_name``
      - *(auto: task's own bundle)*
      - Name of a configured Dag bundle to load the ``*.min.mjs`` bundle from. It must name a bundle in
-       ``[dag_processor] dag_bundle_config_list``.
+       ``[dag_processor] dag_bundle_config_list``. Only needed when more than one ``NodeCoordinator`` is
+       configured.
    * - ``node_executable``
      - ``"node"``
      - Path to the ``node`` binary. Defaults to ``node`` on ``$PATH``.
@@ -561,11 +564,11 @@ All ``kwargs`` in the ``coordinators`` config entry are passed to the
 
   **Locating the bundle.** The ``*.min.mjs`` bundle always lives in a Dag bundle:
 
-  * Set ``dag_bundle_name`` to load the bundle from a configured Dag bundle, so it is delivered
-    and versioned through the same bundle machinery as your Dags. The task uses the version that
+  * Leave ``dag_bundle_name`` unset (the default) to load the bundle from the **task's own** Dag bundle,
+    pinned to the version the run was created with. This is all you need with a single ``NodeCoordinator``.
+  * With more than one ``NodeCoordinator``, set ``dag_bundle_name`` on each to a different Dag bundle, so
+    the Dag importer can tell which coordinator parses which bundle. The task uses the version that Dag
     bundle is on when it starts, pinned for the whole task.
-  * Leave it unset (the default) to load the bundle from the **task's own** Dag bundle, pinned to the
-    version the run was created with.
 
 Limitations
 -----------

airflow-core/src/airflow/config_templates/config.yml

@@ -2192,9 +2192,11 @@ sdk:
         versions).
 
         A coordinator finds its artifacts in the task's own Dag bundle, or in the
-        Dag bundle named by its ``dag_bundle_name`` kwarg. Two coordinators whose
-        Dag importers parse the same file extension need different
-        ``dag_bundle_name`` values.
+        Dag bundle named by its ``dag_bundle_name`` kwarg. ``dag_bundle_name`` is
+        only needed when the same coordinator class is configured more than once
+        (for example, two ``JavaCoordinator`` entries). Each one must then name
+        its own Dag bundle, otherwise the Dag importer cannot tell which
+        coordinator should parse an artifact. With one entry per class, omit it.
 
         An entry may also carry an optional ``extra`` object for additional
         information associated with the coordinator that the coordinator itself

go-sdk/README.md

@@ -292,8 +292,8 @@ the full range of task states, and alternate XCom backends without implementing
   queue_to_coordinator = {"golang": "go"}
   ```
 
-  `dag_bundle_name` names the Dag bundle the coordinator scans for executable bundles. Omit it to ship
-  them in the same Dag bundle as the Python stub Dag. `queue_to_coordinator` routes stub tasks with
+  `dag_bundle_name` is optional. Omit it and the coordinator finds executable bundles in the task's own
+  Dag bundle, the one that holds the Python stub Dag. Set it, as here, to keep them in a separate Dag bundle. `queue_to_coordinator` routes stub tasks with
   `queue="golang"` to this Go coordinator.
 
   > [!IMPORTANT]

java-sdk/README.md

@@ -120,6 +120,9 @@ Now `cd example` into the example project, and
   export AIRFLOW__SDK__QUEUE_TO_COORDINATOR='{"java": "java"}'
   ```
 
+  With a single `JavaCoordinator`, `dag_bundle_name` is optional. It is set here because the JARs live in
+  `build/bundle`, outside the Dags folder; omit it if you ship the JARs in the same Dag bundle as the stub Dag.
+
 * Ensure the Connection and Variable needed by the example DAG are available:
 
   ```bash

ts-sdk/README.md

@@ -99,9 +99,10 @@ queue_to_coordinator = {"typescript": "ts"}
 ```
 
 The stub Dag's own Dag bundle is searched recursively for `*.min.mjs` bundles built with `airflow-ts-pack`
-(see [Packing bundles](#packing-bundles)), which embeds the Airflow metadata in the bundle itself. To keep
-the `*.min.mjs` bundles in a separate Dag bundle, set `dag_bundle_name` to a bundle configured in
-`[dag_processor] dag_bundle_config_list`.
+(see [Packing bundles](#packing-bundles)), which embeds the Airflow metadata in the bundle itself. Set
+`dag_bundle_name` only when you configure more than one `NodeCoordinator`: each must then name its own Dag
+bundle from `[dag_processor] dag_bundle_config_list`, otherwise the Dag importer cannot tell which coordinator
+should parse a bundle.
 
 TypeScript entrypoint:
 

ts-sdk/example/README.md

@@ -83,6 +83,9 @@ export AIRFLOW__SDK__COORDINATORS='{
 export AIRFLOW__SDK__QUEUE_TO_COORDINATOR='{"typescript": "ts"}'
 ```
 
+With a single `NodeCoordinator`, `dag_bundle_name` is optional. It is set here because the bundle lives in
+`dist/`, outside the Dags folder; omit it if you copy the bundle into the same Dag bundle as the stub Dags.
+
 Copy both files in `dags/` into your Airflow Dags folder.
 
 The example also reads one Variable and one Connection: