docs: refresh Public Interface & align how-to guides for Airflow 3.0+ #52297

sunank200 · 2025-06-26T16:19:16Z

This PR refreshed public-airflow-interface.rst for Airflow 3.0+, with the airflow.sdk, deprecating direct metadata DB access in task code, and pointing users to Task Context, REST API, or Python Client.

This patch updates user how-to guides (connections, custom-operator, extra-link) to:
– Add warning against direct metadata-model imports
– Switch examples from airflow.models.* to airflow.sdk.* classes and types

closes: #51590
closes: #52250

^ Add meaningful description above
Read the Pull Request Guidelines for more information.
In case of fundamental code changes, an Airflow Improvement Proposal (AIP) is needed.
In case of a new dependency, check compliance with the ASF 3rd Party License Policy.
In case of backwards incompatible changes please leave a note in a newsfragment file, named {pr_number}.significant.rst or {issue_number}.significant.rst, in airflow-core/newsfragments.

potiuk · 2025-06-26T21:53:40Z

Actually - I am not sure if we need to make a distinction vs. Airlfow 3 and Airflow 2 - as soon as we have a clearer way of showing that you are in Airflow 2 or Airflow 3, this should be likely more distinguishable. But what I would likely do here is just to focus on Airflow 3 public interface and have a BOLD LETTTERS at the top - somethign like

This is Public interface for Airflow 3 - if you look for Airflow 2 public interface look -> Link to 2.11 version of the interface.

potiuk · 2025-06-26T21:55:06Z

Sorry - public interface of course not security model :) .. My mind was wandering a bit to another similar change we need to do.

sunank200 · 2025-07-01T18:30:35Z

Actually - I am not sure if we need to make a distinction vs. Airlfow 3 and Airflow 2 - as soon as we have a clearer way of showing that you are in Airflow 2 or Airflow 3, this should be likely more distinguishable. But what I would likely do here is just to focus on Airflow 3 public interface and have a BOLD LETTTERS at the top - somethign like

This is Public interface for Airflow 3 - if you look for Airflow 2 public interface look -> Link to 2.11 version of the interface.

@potiuk I have done the change as suggested above.

airflow-core/docs/core-concepts/xcoms.rst

airflow-core/docs/public-airflow-interface.rst

amoghrajesh

I think these are my last set of comments @sunank200.
Looking in pretty good shape!

airflow-core/docs/core-concepts/xcoms.rst

airflow-core/docs/public-airflow-interface.rst

…data direct access change

…irflow.sdk

Co-Authored-By: Amogh Desai <[email protected]>

… public

amoghrajesh

Looks good, we can come back at improvements at a later point again.
Please address the one comment I have prior to merge.

airflow-core/docs/core-concepts/xcoms.rst

eladkal

Not sure if we can get it to 3.0.3 given the next RC? marked it for 3.0.4 for now
cc @kaxil

potiuk · 2025-07-08T09:32:24Z

Not sure if we can get it to 3.0.3 given the next RC? marked it for 3.0.4 for now cc @kaxil

We have RC5 coming. We can get it in as it is doc-only.

github-actions · 2025-07-08T09:34:01Z

Backport failed to create: v3-0-test. View the failure log Run details

Status	Branch	Result
❌	v3-0-test

You can attempt to backport this manually by running:

cherry_picker e8767b6 v3-0-test

This should apply the commit to the v3-0-test branch and leave the commit in conflict state marking
the files that need manual conflict resolution.

After you have resolved the conflicts, you can continue the backport process by running:

cherry_picker --continue

…apache#52297) * docs: Update public interface documentation for Airflow 3.0+ for metadata direct access change * docs: replace direct metadata model imports in how-to examples with airflow.sdk * Make Public interface for Airflow 3 and add link for Airflow 2.11 * Fix PR comments * Update airflow-core/docs/public-airflow-interface.rst Co-Authored-By: Amogh Desai <[email protected]> * Fix PR comments * Remove duplicates and remove RuntimeTaskInstanceProtocol as it is not public * Fix PR comments --------- Co-authored-by: Amogh Desai <[email protected]> (cherry picked from commit e8767b6)

…#52297) (#53011) * docs: Update public interface documentation for Airflow 3.0+ for metadata direct access change * docs: replace direct metadata model imports in how-to examples with airflow.sdk * Make Public interface for Airflow 3 and add link for Airflow 2.11 * Fix PR comments * Update airflow-core/docs/public-airflow-interface.rst * Fix PR comments * Remove duplicates and remove RuntimeTaskInstanceProtocol as it is not public * Fix PR comments --------- (cherry picked from commit e8767b6) Co-authored-by: Ankit Chaurasia <[email protected]> Co-authored-by: Amogh Desai <[email protected]>

…apache#52297) * docs: Update public interface documentation for Airflow 3.0+ for metadata direct access change * docs: replace direct metadata model imports in how-to examples with airflow.sdk * Make Public interface for Airflow 3 and add link for Airflow 2.11 * Fix PR comments * Update airflow-core/docs/public-airflow-interface.rst Co-Authored-By: Amogh Desai <[email protected]> * Fix PR comments * Remove duplicates and remove RuntimeTaskInstanceProtocol as it is not public * Fix PR comments --------- Co-authored-by: Amogh Desai <[email protected]>

boring-cyborg bot added the kind:documentation label Jun 26, 2025

sunank200 requested review from kaxil, cmarteepants, phanikumv, ashb and amoghrajesh June 26, 2025 16:19

sunank200 force-pushed the Update-Public-Interface branch from 6a2ff20 to f7daae6 Compare June 26, 2025 16:32

sunank200 force-pushed the Update-Public-Interface branch 2 times, most recently from e95f771 to e6fa6ae Compare July 1, 2025 18:29

sunank200 force-pushed the Update-Public-Interface branch 2 times, most recently from f3dfd49 to 7cfa2bf Compare July 1, 2025 18:38

sunank200 requested a review from potiuk July 2, 2025 06:52

amoghrajesh reviewed Jul 2, 2025

View reviewed changes

sunank200 force-pushed the Update-Public-Interface branch from 7cfa2bf to 3f0877e Compare July 2, 2025 12:25

sunank200 requested a review from amoghrajesh July 2, 2025 12:41

sunank200 force-pushed the Update-Public-Interface branch 3 times, most recently from b1f7707 to ca2b9b3 Compare July 2, 2025 15:18

amoghrajesh reviewed Jul 3, 2025

View reviewed changes

sunank200 force-pushed the Update-Public-Interface branch 3 times, most recently from 451b4a2 to 6323a86 Compare July 3, 2025 11:41

sunank200 requested a review from amoghrajesh July 3, 2025 16:23

sunank200 force-pushed the Update-Public-Interface branch 2 times, most recently from 2fb6cde to d11695b Compare July 3, 2025 17:17

kaxil mentioned this pull request Jul 3, 2025

docs: clarify AssetAlias usage with detailed explanation and examples #52259

Closed

eladkal reviewed Jul 3, 2025

View reviewed changes

airflow-core/docs/public-airflow-interface.rst Outdated Show resolved Hide resolved

sunank200 force-pushed the Update-Public-Interface branch 2 times, most recently from dd7ff71 to 2935862 Compare July 8, 2025 07:18

sunank200 and others added 7 commits July 8, 2025 13:10

docs: Update public interface documentation for Airflow 3.0+ for meta…

60ef064

…data direct access change

docs: replace direct metadata model imports in how-to examples with a…

2f6302e

…irflow.sdk

Make Public interface for Airflow 3 and add link for Airflow 2.11

14f4ed0

Fix PR comments

541d363

Update airflow-core/docs/public-airflow-interface.rst

be34eb9

Co-Authored-By: Amogh Desai <[email protected]>

Fix PR comments

aa53321

Remove duplicates and remove RuntimeTaskInstanceProtocol as it is not…

f80fbd6

… public

sunank200 force-pushed the Update-Public-Interface branch from 2935862 to f80fbd6 Compare July 8, 2025 07:25

amoghrajesh approved these changes Jul 8, 2025

View reviewed changes

airflow-core/docs/core-concepts/xcoms.rst Outdated Show resolved Hide resolved

Fix PR comments

f60e0e1

eladkal added the backport-to-v3-0-test Mark PR with this label to backport to v3-0-test branch label Jul 8, 2025

eladkal added this to the Airflow 3.0.4 milestone Jul 8, 2025

eladkal approved these changes Jul 8, 2025

View reviewed changes

potiuk modified the milestones: Airflow 3.0.4, Airflow 3.0.3 Jul 8, 2025

potiuk approved these changes Jul 8, 2025

View reviewed changes

potiuk merged commit e8767b6 into apache:main Jul 8, 2025
58 checks passed

potiuk mentioned this pull request Jul 8, 2025

[v3-0-test] docs: refresh Public Interface & align how-to guides for Airflow 3.0+… #53011

Merged

docs: refresh Public Interface & align how-to guides for Airflow 3.0+ #52297

docs: refresh Public Interface & align how-to guides for Airflow 3.0+ #52297

Conversation

sunank200 commented Jun 26, 2025 • edited by eladkal Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

potiuk commented Jun 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

potiuk commented Jun 26, 2025

Uh oh!

sunank200 commented Jul 1, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

amoghrajesh left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

amoghrajesh left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

eladkal left a comment

Choose a reason for hiding this comment

Uh oh!

potiuk commented Jul 8, 2025

Uh oh!

Uh oh!

github-actions bot commented Jul 8, 2025

Backport failed to create: v3-0-test. View the failure log Run details

Uh oh!

Uh oh!

sunank200 commented Jun 26, 2025 •

edited by eladkal

Loading

potiuk commented Jun 26, 2025 •

edited

Loading