This is an automated email from the ASF dual-hosted git repository.
jason810496 pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/main by this push:
new 549ed6b7468 Split ts-sdk contributor docs out of the npm README
(#72096)
549ed6b7468 is described below
commit 549ed6b7468aa76bf1fac493c15fb26521335489
Author: Jason(Zhe-You) Liu <[email protected]>
AuthorDate: Wed Aug 26 19:52:06 2026 +0800
Split ts-sdk contributor docs out of the npm README (#72096)
---
ts-sdk/DEVELOPMENT.md | 184 +++++++++++++++++++++++++++++++++++++++++++++++
ts-sdk/README.md | 180 +++++-----------------------------------------
ts-sdk/example/README.md | 4 +-
ts-sdk/package.json | 1 +
4 files changed, 205 insertions(+), 164 deletions(-)
diff --git a/ts-sdk/DEVELOPMENT.md b/ts-sdk/DEVELOPMENT.md
new file mode 100644
index 00000000000..92a4a60d7f4
--- /dev/null
+++ b/ts-sdk/DEVELOPMENT.md
@@ -0,0 +1,184 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+ -->
+
+# Developing the Airflow TypeScript SDK
+
+Contributor and release-manager reference for `apache-airflow-ts-sdk`. See
+[`README.md`](README.md) for the user-facing package documentation.
+
+## Building and testing
+
+```bash
+pnpm install
+pnpm test
+pnpm run typecheck
+pnpm run build
+pnpm run verify:package
+```
+
+The committed lockfile and `pnpm-workspace.yaml` define the dependency security
+policy. Newly released dependency versions must age for 14 days before they
+can enter the lockfile, transitive dependencies cannot use Git or arbitrary
+tarball sources, and only explicitly approved dependencies can run lifecycle
+build scripts. Review changes to both files together when updating
dependencies.
+
+`verify:package` creates the npm tarball, rejects files outside the published
+runtime allowlist, installs it into a clean temporary project, and smoke-tests
+every `exports` entry point and the `bin` executable. The required paths are
+derived from `package.json`, so a new export subpath is covered automatically.
+
+`tsconfig.build.json` turns off `sourceMap` and `declarationMap` that the base
+`tsconfig.json` enables. The published tarball ships `dist` but not `src`, so
+emitted maps would point at files the consumer never receives — the allowlist
+rejects them rather than shipping dangling maps. Local `pnpm run typecheck`
+still uses the base config, so editor tooling is unaffected.
+
+Without a local pnpm install, [prek](https://prek.j178.dev) can compile the SDK
+or verify the package with its own managed node + pnpm toolchain:
+
+```bash
+prek run compile-ts-sdk --all-files
+prek run --hook-stage manual verify-ts-sdk-package --all-files
+```
+
+## API reference
+
+The public API reference is generated from the TypeScript sources with
+[TypeDoc](https://typedoc.org/) and published to
+<https://airflow.apache.org/docs/ts-sdk/stable/>.
+
+Build it locally (runs the pinned toolchain in a Node container, so no local
+Node install is needed):
+
+```bash
+breeze build-docs --sdk-docs-only --sdk=typescript
+```
+
+The rendered site is staged at `generated/_build/docs/ts-sdk/stable/`,
alongside
+a `stable.txt` holding the version from `ts-sdk/package.json`. To iterate on
the
+docs directly instead, `npm ci && npm run build` inside `ts-sdk/docs/` writes
to
+`ts-sdk/docs/_build/html/`, and `npm start` rebuilds on change.
+
+CI builds the reference on every change under `ts-sdk/src/` or `ts-sdk/docs/`,
+so a broken docs build fails the PR rather than the release.
+
+### Publishing the API docs
+
+Publishing is a separate, deliberate step — a providers-only publish wave will
+not refresh the SDK docs as a side effect. Trigger the *Publish Docs to S3*
+workflow for the release ref:
+
+```bash
+gh workflow run "Publish Docs to S3" --repo apache/airflow --ref main \
+ -f ref=<RELEASE_REF> \
+ -f include-docs=ts-sdk \
+ -f destination=live
+```
+
+Use `destination=staging` first to check the output, then `live`. Confirm that
+`https://airflow.apache.org/docs/ts-sdk/stable/` resolves (allow time for cache
+invalidation) and that `/docs/ts-sdk/` redirects to it.
+
+## Publishing
+
+The manually dispatched `Release TypeScript SDK` workflow first builds, tests,
+and hashes one package tarball without OIDC permissions. Its protected publish
+job then either uses [npm's staged-publishing
flow](https://docs.npmjs.com/staged-publishing/)
+or publishes the formal release directly.
+
+npm's registry supports only one trusted-publisher configuration per package,
+so both release paths share a single configuration pinned to a single GitHub
+environment:
+
+```bash
+npm trust github apache-airflow-ts-sdk \
+ --repo apache/airflow \
+ --file ts-sdk-release.yml \
+ --environment ts-sdk-npm-release \
+ --allow-stage-publish \
+ --allow-publish
+```
+
+Confirm it with `npm trust list apache-airflow-ts-sdk`. A second `npm trust
+github` for the same package is rejected, so replace an outdated configuration
+with `npm trust revoke` first.
+
+Because the registry cannot express "stage only" and "publish only" as separate
+relationships, what separates the two paths is the GitHub environment gate
+rather than an npm-side permission split. Require reviewers and prevent
+self-review on `ts-sdk-npm-release`, restrict its deployment tags to
+`ts-sdk/*`, and protect those tags from updates and deletion with a repository
+ruleset. The pinned `--environment` claim means a workflow edit that drops the
+gate loses the ability to publish at all.
+
+Create and push a `ts-sdk/<version>` tag whose version exactly matches
+`package.json`, then dispatch the workflow on that same tag so npm provenance
+names the source commit that produced the tarball. The tag must already exist
+on `apache/airflow` before the dispatch below can reference it as `--ref`:
+
+```bash
+git tag ts-sdk/0.1.0-beta1 <commit-sha>
+git push upstream ts-sdk/0.1.0-beta1
+```
+
+To submit the package to npm's private staging area for review, run:
+
+```bash
+gh workflow run ts-sdk-release.yml --repo apache/airflow --ref
ts-sdk/0.1.0-beta1 \
+ -f release_type=staged \
+ -f tag=ts-sdk/0.1.0-beta1 \
+ -f npm_tag=beta
+```
+
+The publish job calls `npm stage publish` only after the unprivileged build job
+has uploaded a checksummed tarball. The version is not publicly installable
+until a maintainer reviews and approves it with 2FA. The following commands
+require npm 11.15 or later:
+
+```bash
+npm stage list apache-airflow-ts-sdk
+npm stage view <stage-id>
+npm stage download <stage-id>
+npm stage approve <stage-id>
+```
+
+The approval cannot run through the trusted-publisher workflow because npm
+requires interactive proof of presence. Reject an unsuitable staged version
+with `npm stage reject <stage-id>`. Do not run the formal workflow for a
version
+that is already staged; approve or reject that staged version instead.
+
+To publish directly without npm's staging review, trigger the formal path:
+
+```bash
+gh workflow run ts-sdk-release.yml --repo apache/airflow --ref
ts-sdk/0.1.0-beta1 \
+ -f release_type=formal \
+ -f tag=ts-sdk/0.1.0-beta1 \
+ -f npm_tag=beta
+```
+
+Use `latest` for stable releases. A prerelease may only use the channel derived
+from its own prerelease identifier (`0.1.0-beta1` → `beta`) or `next` —
+`scripts/validate-release-inputs.mjs` rejects any other tag. The workflow also
+rejects a dispatch that would move the selected npm dist-tag backward as of
+when it runs. For a staged release, the dist-tag only actually moves later, at
+`npm stage approve` time, which is not re-validated — approve staged versions
+in the order they were requested so the dist-tag does not regress. Both
+publication paths use short-lived npm OIDC credentials and automatically
+publish provenance. After verifying the trusted-publisher setup, disable
+token-based publishing and revoke obsolete npm automation tokens.
diff --git a/ts-sdk/README.md b/ts-sdk/README.md
index fc6781d2113..439a79e522e 100644
--- a/ts-sdk/README.md
+++ b/ts-sdk/README.md
@@ -167,8 +167,9 @@ Airflow launches the bundled entrypoint with
`--comm=host:port` and
startup message, finds the registered handler for the Dag/task pair, and
reports the terminal task state back to Airflow.
-See [`example/`](example/) for a coordinator-runtime example that packs a
-bundle with `airflow-ts-pack` and uses a Python stub Dag.
+See [`example/`](https://github.com/apache/airflow/tree/main/ts-sdk/example)
for
+a coordinator-runtime example that packs a bundle with `airflow-ts-pack` and
+uses a Python stub Dag.
## Packing bundles
@@ -217,7 +218,8 @@ terminates the task subprocess with SIGTERM or SIGINT.
## Compatibility matrix
Which Airflow TaskInstance states and capabilities this SDK supports. This
table is generated from
-[`capabilities.yaml`](capabilities.yaml); the conformance dimensions are
defined in the
+[`capabilities.yaml`](https://github.com/apache/airflow/blob/main/ts-sdk/capabilities.yaml);
+the conformance dimensions are defined in the
[Language SDK conformance
spec](https://github.com/apache/airflow/blob/main/contributing-docs/30_new_language_sdk.rst).
Do not edit the table by hand — update the manifest and run the
`update-ts-sdk-readme-matrix` prek hook.
@@ -266,162 +268,16 @@ Do not edit the table by hand — update the manifest and
run the
<!-- END AUTO-GENERATED LANG-SDK COMPAT MATRIX -->
-## Development
-
-```bash
-pnpm install
-pnpm test
-pnpm run typecheck
-pnpm run build
-pnpm run verify:package
-```
-
-The committed lockfile and `pnpm-workspace.yaml` define the dependency security
-policy. Newly released dependency versions must age for 14 days before they
-can enter the lockfile, transitive dependencies cannot use Git or arbitrary
-tarball sources, and only explicitly approved dependencies can run lifecycle
-build scripts. Review changes to both files together when updating
dependencies.
-
-`verify:package` creates the npm tarball, rejects files outside the published
-runtime allowlist, installs it into a clean temporary project, and smoke-tests
-every `exports` entry point and the `bin` executable. The required paths are
-derived from `package.json`, so a new export subpath is covered automatically.
-
-`tsconfig.build.json` turns off `sourceMap` and `declarationMap` that the base
-`tsconfig.json` enables. The published tarball ships `dist` but not `src`, so
-emitted maps would point at files the consumer never receives — the allowlist
-rejects them rather than shipping dangling maps. Local `pnpm run typecheck`
-still uses the base config, so editor tooling is unaffected.
-
-Without a local pnpm install, [prek](https://prek.j178.dev) can compile the SDK
-or verify the package with its own managed node + pnpm toolchain:
-
-```bash
-prek run compile-ts-sdk --all-files
-prek run --hook-stage manual verify-ts-sdk-package --all-files
-```
-
-## API reference
-
-The public API reference is generated from the TypeScript sources with
-[TypeDoc](https://typedoc.org/) and published to
-<https://airflow.apache.org/docs/ts-sdk/stable/>.
-
-Build it locally (runs the pinned toolchain in a Node container, so no local
-Node install is needed):
-
-```bash
-breeze build-docs --sdk-docs-only --sdk=typescript
-```
-
-The rendered site is staged at `generated/_build/docs/ts-sdk/stable/`,
alongside
-a `stable.txt` holding the version from `ts-sdk/package.json`. To iterate on
the
-docs directly instead, `npm ci && npm run build` inside `ts-sdk/docs/` writes
to
-`ts-sdk/docs/_build/html/`, and `npm start` rebuilds on change.
-
-CI builds the reference on every change under `ts-sdk/src/` or `ts-sdk/docs/`,
-so a broken docs build fails the PR rather than the release.
-
-### Publishing the API docs
-
-Publishing is a separate, deliberate step — a providers-only publish wave will
-not refresh the SDK docs as a side effect. Trigger the *Publish Docs to S3*
-workflow for the release ref:
-
-```bash
-gh workflow run "Publish Docs to S3" --repo apache/airflow --ref main \
- -f ref=<RELEASE_REF> \
- -f include-docs=ts-sdk \
- -f destination=live
-```
-
-Use `destination=staging` first to check the output, then `live`. Confirm that
-`https://airflow.apache.org/docs/ts-sdk/stable/` resolves (allow time for cache
-invalidation) and that `/docs/ts-sdk/` redirects to it.
-
-## Publishing
-
-The manually dispatched `Release TypeScript SDK` workflow first builds, tests,
-and hashes one package tarball without OIDC permissions. Its protected publish
-job then either uses [npm's staged-publishing
flow](https://docs.npmjs.com/staged-publishing/)
-or publishes the formal release directly.
-
-npm's registry supports only one trusted-publisher configuration per package,
-so both release paths share a single configuration pinned to a single GitHub
-environment:
-
-```bash
-npm trust github apache-airflow-ts-sdk \
- --repo apache/airflow \
- --file ts-sdk-release.yml \
- --environment ts-sdk-npm-release \
- --allow-stage-publish \
- --allow-publish
-```
-
-Confirm it with `npm trust list apache-airflow-ts-sdk`. A second `npm trust
-github` for the same package is rejected, so replace an outdated configuration
-with `npm trust revoke` first.
-
-Because the registry cannot express "stage only" and "publish only" as separate
-relationships, what separates the two paths is the GitHub environment gate
-rather than an npm-side permission split. Require reviewers and prevent
-self-review on `ts-sdk-npm-release`, restrict its deployment tags to
-`ts-sdk/*`, and protect those tags from updates and deletion with a repository
-ruleset. The pinned `--environment` claim means a workflow edit that drops the
-gate loses the ability to publish at all.
-
-Create and push a `ts-sdk/<version>` tag whose version exactly matches
-`package.json`, then dispatch the workflow on that same tag so npm provenance
-names the source commit that produced the tarball. The tag must already exist
-on `apache/airflow` before the dispatch below can reference it as `--ref`:
-
-```bash
-git tag ts-sdk/1.0.0-beta1 <commit-sha>
-git push upstream ts-sdk/1.0.0-beta1
-```
-
-To submit the package to npm's private staging area for review, run:
-
-```bash
-gh workflow run ts-sdk-release.yml --repo apache/airflow --ref
ts-sdk/1.0.0-beta1 \
- -f release_type=staged \
- -f tag=ts-sdk/1.0.0-beta1 \
- -f npm_tag=beta
-```
-
-The publish job calls `npm stage publish` only after the unprivileged build job
-has uploaded a checksummed tarball. The version is not publicly installable
-until a maintainer reviews and approves it with 2FA. The following commands
-require npm 11.15 or later:
-
-```bash
-npm stage list apache-airflow-ts-sdk
-npm stage view <stage-id>
-npm stage download <stage-id>
-npm stage approve <stage-id>
-```
-
-The approval cannot run through the trusted-publisher workflow because npm
-requires interactive proof of presence. Reject an unsuitable staged version
-with `npm stage reject <stage-id>`. Do not run the formal workflow for a
version
-that is already staged; approve or reject that staged version instead.
-
-To publish directly without npm's staging review, trigger the formal path:
-
-```bash
-gh workflow run ts-sdk-release.yml --repo apache/airflow --ref
ts-sdk/1.0.0-beta1 \
- -f release_type=formal \
- -f tag=ts-sdk/1.0.0-beta1 \
- -f npm_tag=beta
-```
-
-Use `latest` for stable releases and a non-`latest` tag such as `alpha`,
-`beta`, or `rc` for prereleases. The workflow rejects a dispatch that would
-move the selected npm dist-tag backward as of when it runs. For a staged
-release, the dist-tag only actually moves later, at `npm stage approve` time,
-which is not re-validated — approve staged versions in the order they were
-requested so the dist-tag does not regress. Both publication paths use
-short-lived npm OIDC credentials and automatically publish provenance. After
-verifying the trusted-publisher setup, disable token-based publishing and
-revoke obsolete npm automation tokens.
+## Links
+
+- [TypeScript SDK guide (staged docs build from latest
main)](http://apache-airflow-docs.s3-website.eu-central-1.amazonaws.com/docs/apache-airflow/stable/authoring-and-scheduling/language-sdks/typescript.html)
+ — how Airflow runs TypeScript task handlers
+- [API reference
(staged)](http://apache-airflow-docs.s3-website.eu-central-1.amazonaws.com/docs/ts-sdk/stable/)
+ — generated from the TypeScript sources
+- [Source](https://github.com/apache/airflow/tree/main/ts-sdk) — the `ts-sdk/`
+ directory of the Apache Airflow monorepo
+- [Issues](https://github.com/apache/airflow/issues) — bug reports and feature
+ requests
+- [Website](https://airflow.apache.org) ·
[Slack](https://s.apache.org/airflow-slack)
+- [Developing this
package](https://github.com/apache/airflow/blob/main/ts-sdk/DEVELOPMENT.md)
+ — local build, docs, and the release workflow
diff --git a/ts-sdk/example/README.md b/ts-sdk/example/README.md
index 1ea267bdedf..d8c690eec90 100644
--- a/ts-sdk/example/README.md
+++ b/ts-sdk/example/README.md
@@ -62,12 +62,12 @@ point it at the example bundle directory:
```bash
export AIRFLOW__SDK__COORDINATORS='{
- "node": {
+ "ts": {
"classpath": "airflow.sdk.coordinators.node.NodeCoordinator",
"kwargs": {"bundles_root":
["/absolute/path/to/airflow/ts-sdk/example/dist"]}
}
}'
-export AIRFLOW__SDK__QUEUE_TO_COORDINATOR='{"typescript": "node"}'
+export AIRFLOW__SDK__QUEUE_TO_COORDINATOR='{"typescript": "ts"}'
```
Copy `dags/typescript_example.py` into your Airflow Dags folder.
diff --git a/ts-sdk/package.json b/ts-sdk/package.json
index 7f13f825e2f..b09a714106a 100644
--- a/ts-sdk/package.json
+++ b/ts-sdk/package.json
@@ -4,6 +4,7 @@
"packageManager": "[email protected]",
"description": "TypeScript Task SDK for Apache Airflow task handlers",
"license": "Apache-2.0",
+ "author": "Apache Software Foundation",
"type": "module",
"main": "./dist/index.js",
"types": "./dist/index.d.ts",
