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. >
