uranusjr commented on code in PR #70717:
URL: https://github.com/apache/airflow/pull/70717#discussion_r3689984227
##########
contributing-docs/30_new_language_sdk.rst:
##########
@@ -333,6 +336,162 @@ Error handling
SHOULD propagate it as an error to the task function.
+Conformance
+-----------
+
+The sections above describe *how* to build an SDK. This section defines *what*
an
+SDK must do to be considered conformant: which TaskInstance states its runtime
is
+expected to report and which optional capabilities it may offer. Because SDKs
mature
+at different rates, they are not required to be identical; each one declares
the
+subset it actually supports.
+
+The key words MUST, SHOULD, and MAY are used as described in :rfc:`2119`.
+
+TaskInstance-state conformance
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A running task reports its outcome to the supervisor as one of a small set of
+state transitions, each carried by a specific message on the ``--comm`` socket
+(see `Message types`_). Only the states a subprocess can *emit* are part of SDK
+conformance; scheduler-owned states (``queued``, ``scheduled``, ``running``,
+``restarting``, ``upstream_failed``) are set by Airflow and are never sent by
the
+runtime, so they are out of scope here.
+
+.. list-table:: TaskInstance-state conformance
+ :header-rows: 1
+ :widths: 20 15 65
+
+ * - State
+ - Tier
+ - How it is reported / notes
+ * - ``success``
+ - MUST
+ - ``SucceedTask``, or a clean process exit (exit code 0).
+ * - ``failed``
+ - MUST
+ - ``TaskState`` with ``"state": "failed"``; also inferred from a non-zero
+ exit if no terminal message was sent.
+ * - ``up_for_retry``
+ - MUST
+ - ``RetryTask`` when the task fails but retries remain. The failure detail
+ key is ``retry_reason`` (not ``reason``).
+ * - ``skipped``
+ - SHOULD
+ - ``TaskState`` with ``"state": "skipped"``, for branching / skip
semantics.
+ * - ``deferred``
+ - MAY
+ - ``DeferTask``. Requires the SDK to bridge to the triggerer.
+ * - ``up_for_reschedule``
+ - MAY
+ - ``RescheduleTask``, for reschedule-mode sensors.
+ * - ``awaiting_input``
+ - MAY
+ - ``AwaitInputTask``, for human-in-the-loop tasks.
+ * - ``removed``
+ - MAY
+ - ``TaskState`` with ``"state": "removed"``.
+
+An SDK that only implements the MUST tier can already run ordinary tasks to
+success or failure with retries; the SHOULD and MAY tiers unlock branching,
+deferral, reschedule sensors, and human-in-the-loop.
+
+Runtime capabilities
+~~~~~~~~~~~~~~~~~~~~~~
+
+Runtime capabilities describe what a task *body* can do while it executes,
regardless of
+whether the task was declared in a Python Dag (via ``@task.stub``) or in a
native Dag
+authored in the target language. An SDK declares each one independently.
+
+``mixed-lang-stub-target`` (MUST)
+ The SDK can execute a task declared in a Python Dag with the ``@task.stub``
+ decorator. This is the primary execution path for every Language SDK.
+
+``task-logging`` (MUST)
+ The SDK forwards the task's log output — stdout / stderr and any
structured log
+ records — to the supervisor over the ``--logs`` socket, so it surfaces in
the task
+ log exactly like a Python task. Remote log *storage* (S3, GCS, …) is
handled
+ uniformly by the supervisor of this and is not part of SDK conformance.
Review Comment:
```suggestion
log exactly like a Python task. A remote log *storage* (S3, GCS, …) is
handled
uniformly by the supervisor and thus not part of SDK conformance.
```
--
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]
