From d1439dfc135c270ca87b9fea51fd11aa1817d4ba Mon Sep 17 00:00:00 2001 From: Amogh Desai Date: Wed, 28 May 2025 17:59:16 +0530 Subject: [PATCH] Refine the execution api versioning doc to reflect reality --- contributing-docs/19_execution_api_versioning.rst | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/contributing-docs/19_execution_api_versioning.rst b/contributing-docs/19_execution_api_versioning.rst index 189aed58a5221..c9d4590950829 100644 --- a/contributing-docs/19_execution_api_versioning.rst +++ b/contributing-docs/19_execution_api_versioning.rst @@ -25,9 +25,14 @@ Why? ---- Airflow components (e.g., workers, API servers) could be deployed independently. This can lead -to version mismatches—for example, a worker using Task SDK 1.0.1 (requiring Airflow >=3.0.1) while the -API server is still on 3.0.0. Without versioning, such mismatches can cause runtime failures or subtle bugs. -A strict versioning model allows older clients to continue working with newer servers, enabling safe, incremental upgrades. +to version mismatches—for example, a worker using Task SDK 1.0.0 (requiring Airflow >=3.0.0) while the +API server has been upgraded to 3.0.1. Without versioning, such mismatches can cause runtime failures or subtle bugs. +Enforcing a clear versioning contract ensures backward compatibility and allows for safe, incremental upgrades +across different components. + +Note: We're prioritizing backward compatibility, older clients should continue to work seamlessly with newer servers. +Since the client (Task SDK) and server (API) are still coupled, we can look at forward compatibility once we have a +clear versioning strategy between Task SDK and Airflow Core. Versioning Principles ---------------------