Repository navigation
Add a Language SDK spec to the Task SDK docs - #72765
Merged
jason810496 merged 4 commits intoSep 17, 2026
Merged
Conversation
jason810496
requested review from
amoghrajesh,
ashb and
kaxil
as code owners
September 9, 2026 03:31
jason810496
force-pushed
the
docs/lang-sdk/language-sdk-spec
branch
from
September 9, 2026 05:21
c6bf9f8 to
95cf5a6
Compare
jason810496
marked this pull request as draft
September 9, 2026 06:09
jason810496
force-pushed
the
docs/lang-sdk/language-sdk-spec
branch
4 times, most recently
from
September 9, 2026 06:23
5801b9b to
497738b
Compare
Three Lang SDKs are designing their user-facing authoring interfaces at once, and each was settling the same questions inside its own ADR: what separates a task handler from a native Dag, what to call the thing that holds either of them, and where a task body gets its context and client. Naming those once, somewhere every SDK's docs can point at, means a Go, Java, or TypeScript author reads about the same concepts under different spellings rather than three unrelated vocabularies.
jason810496
force-pushed
the
docs/lang-sdk/language-sdk-spec
branch
from
September 9, 2026 07:10
497738b to
dd4df43
Compare
1 task done
jason810496
marked this pull request as ready for review
September 9, 2026 08:22
The name should say what the SDK registers, and what it registers is a task: Python declares it with @task.stub, gives it a task_id, and the SDK supplies only its body. "Handler" described the callable rather than the thing it stands for, leaving these docs using a word no other part of Airflow uses for a task.
ashb
reviewed
Sep 9, 2026
ashb
reviewed
Sep 9, 2026
ashb
reviewed
Sep 9, 2026
Python declares the task; an SDK supplies only its body. Naming the SDK object after the task overloads a word the native surface already uses for something the user creates with dag.Task, so it names the role the SDK actually plays instead.
jason810496
commented
Sep 14, 2026
pierrejeambrun
approved these changes
Sep 16, 2026
1 task done
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
From my perspative, it's necessary to introduce the generic user-facing interface spec for all the SDKs. To make sure user (or agents) that work on the further SDKs still respect the existing terms and convenstion (e.g. using
TaskHandleras interface name for the mixed-language Task instead of mentioning the "Dag" term).What
I intentionally keep this as a pubic task-sdk docs instead of folding in the
contributing-docs/30_new_language_sdk.rst. Since the doc only describes the public user interface instead of the internal implementation detail (this doc doesn't mention the msgpack, execution API, etc).Was generative AI tooling used to co-author this PR?