I also attempted to migrate and can say that such movement can be confusing.
And most users just hitting "Google" will find the "old" examples for
the next period of time. Even today sometimes my results in "Google"
refer to outdated serversion and not to "/stable" branch of docs.
Unfortunately I have currently no capacity but to eae migration for
users I would really appreciate if 2.11 could have a shim layer that
airflow-sdk is an alias for the respective model classes. Then users
could (1) start migration early and (2) are not confused when reading
the 3.0 docs while still being on 2.x...
On 05.05.25 15:49, Amogh Desai wrote:
Fair point, thanks for raising it here.
There are two cases to consider in my opinion:
*Case 1: Users still on AF2*
These users shouldn’t face much confusion as long as they’re following the
AF2 docs,
which contains no references to the *sdk* module. When they eventually
migrate to AF3,
they should be able to bulk replace models with the corresponding *sdk*
imports.
Also, I was under the impression that ruff already does this as part of the
migration guide.
Is that not the case?
*Case 2: Users who have migrated (or are migrating) to Airflow 3*
These users should already be using the sdk companions if they’ve followed
the migration guide.
The guide should have helped update all relevant imports for them.
Now, regarding the docs:
The bad thing is that even Airflow 3 docs have a mixture of those"
If that’s true, we should definitely fix it -- soon.
I think the one action item we should address is to clearly communicate
that the documentation is
versioned, and probably in the docs (your point 4).
A lot of users land on specific pages via google searches, and if they
unknowingly
end up on the wrong version (e.g., Airflow 3 docs when still using Airflow
2), they could
be misled by mixed or outdated imports.
Thanks & Regards,
Amogh Desai
On Mon, May 5, 2025 at 6:28 PM Jarek Potiuk <ja...@potiuk.com> wrote:
Following the question of the user here:
https://apache-airflow.slack.com/archives/CCQ7EGB1P/p1746442613931879?thread_ts=1746430604.330269&cid=CCQ7EGB1P
The user asked which package they can install to be able to do "from
airflow.sdk import Variable". Turns out they are on Airflow 2.
I think the user got quite confused about task.sdk and "from airflow.sdk"
because this is what they **might** see in our docs without realising it's
for Airflow 3 rather than Airflow 2.
I wonder how we should communicate stuff now in the transition period in
our docs and what we should tell our users. Should we tell them to use:
1. from airflow.models Import Variables
or
2. from airflow.sdk import Variables
The first one allows migration from Airflow 2. And no-one will switch to
`from airlfow.sdk` before they migrate unless we will make task.sdk
possible to be installed in Airflow 2 (it can't be currently).
The bad thing is that even Airflow 3 docs have a mixture of those. There
are many places where we still use "from airflow.models" and a number of
places where we already say "from airflow.sdk" and that can be - I think -
terribly confusing for users who are still using Airflow 2 (it will work
both ways for Airflow 3 of course, so people are likely to end up with
mixture of those as well - depending from where they are copy&pasting
stuff.
Few questions:
1) Do we care about consistency (especially now)?
2) If we do - do we suggest users to make bulk replacement of "from
airflow.models" from `from airflow.sdk` after they migrate? Otherwise the
result will be - inevitably - a mixture of those.
3) Or maybe we should come up with a way to install something (or even have
it in airflow 2.11) to be able to switch to `from airflow.sdk` in Airflow
2.
4) If not 3 (or even independently from 3) - should we have some way in
airflow 3 docs to indicate that this is Airflow 3 syntax-only and that they
should use "from airflow.models" in Airflow 2 to avoid similar confusion as
the slack user had?
Were there any thoughts and discussion about it before? Maybe I missed it?
J.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@airflow.apache.org
For additional commands, e-mail: dev-h...@airflow.apache.org
