jason810496 opened a new issue, #67110:
URL: https://github.com/apache/airflow/issues/67110
### Background
The May 13 dev@ thread on AIP-108 ([thread][thread]) closed on these points:
- `JavaCoordinator` ships inside the Task SDK
(`airflow.sdk.coordinators.java`)
rather than as a separate distribution, on the condition that the
coordinator interface is **experimental** until a second non-Python SDK
(Go is the named candidate) validates it.
- André Ahlert raised an open point that the AIP marks the interface
experimental but does not define **what graduates it out**. Without that,
"experimental" has no exit condition.
Today neither `BaseCoordinator` nor `JavaCoordinator` carries any marker
that tells users the interface may change:
- `task-sdk/src/airflow/sdk/execution_time/coordinator.py:175` — `class
BaseCoordinator:`
- `task-sdk/src/airflow/sdk/coordinators/java/coordinator.py:33` — `class
JavaCoordinator(BaseCoordinator):`
Their docstrings describe the configuration shape and contract, but there
is no warning about stability and no acceptance gate for promoting the
interface to stable.
### What needs to happen
1. Add an explicit experimental marker to `BaseCoordinator` and
`JavaCoordinator` — at minimum a docstring banner; ideally a runtime
warning when a user-defined subclass is instantiated outside of
`airflow.sdk.coordinators.*`.
2. Document the same status on the public docs page that lands with
AIP-108 (coordinator user guide) and on the `[sdk] coordinators` config
entry description.
3. Write explicit **graduation criteria** in the coordinator user guide:
what has to be true before the interface is removed from experimental
and the public API is frozen. Suggested initial criteria, subject to
review:
- At least one additional non-Python language SDK lands and uses
`BaseCoordinator` without requiring breaking changes to the base
class.
- The IPC / wire-protocol decisions deferred to AIP-109 are accepted.
- No outstanding open issue tagged `AIP-108: Coordinator` requires a
breaking change to `BaseCoordinator`'s public surface.
4. Decide and document the deprecation policy that applies while the
interface is experimental (e.g. breaking changes allowed in any
Task SDK minor release, with a one-cycle deprecation notice for
config-key renames).
### Acceptance criteria
- `BaseCoordinator` and `JavaCoordinator` docstrings both state the
interface is experimental and link to the graduation criteria.
- The coordinator user guide has a section titled "Stability and
graduation" with the criteria above (or a refined version after review).
- The `[sdk] coordinators` config docs include a one-line experimental
notice.
- An issue or section in the AIP-108 board tracks each graduation
criterion so progress against the exit conditions is visible.
### Context
- Dev@ thread:
<https://lists.apache.org/thread/gjot4bxj9kygj2fk76kx6tyg8s4hr057>
(see André Ahlert's message dated 2026-05-13 and Jens Scheffler's
follow-up on 2026-05-13 about keeping the public API experimental until
multi-language patterns are clear).
- AIP-108 wiki:
<https://cwiki.apache.org/confluence/display/AIRFLOW/AIP-108+Language+Task+SDK+and+the+Language+Coordinator+Layer>
- Originating PRs that landed the coordinator in the SDK:
apache/airflow#65956, apache/airflow#65958.
- Related: #66838 (pluggable communication channels) — a likely source of
pre-graduation breaking changes.
[thread]: https://lists.apache.org/thread/gjot4bxj9kygj2fk76kx6tyg8s4hr057
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
