You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@airflow.apache.org by Constance Martineau via dev <de...@airflow.apache.org> on 2025/10/15 19:26:48 UTC
[DISCUSS] Finalizing “DAG” terminology for docs and blog ("dag" vs "DAG" vs "Dag")
Reviving this discussion after the canceled vote:
https://lists.apache.org/thread/q7zdogwb76jko3vwz7tlsnl2cn3h3vg9
As mentioned earlier, I plan to *formally call a vote on Monday* to
finalize how we refer to Airflow workflows in writing (docs, tutorials, and
blog posts).
This will *not* affect code (DAG and dag remain as-is in APIs and
decorators). The goal is to set a clear convention for prose so
contributors and vendors can align their content accordingly
Why this matters: We’ve had inconsistent terminology across docs and
repeated PR debates over capitalization. Standardizing will make our
writing clearer, strengthen the Airflow brand, and give external
stakeholders a single reference to follow.
Options for standardization:
1. DAG (all caps)
- Matches existing imports (from airflow.sdk import DAG) and the
broader ecosystem.
- Keeps a nod to the original meaning ("directed acyclic graph")
which still fits conceptually even if we later allow more flexible graph
types
- Counterpoint: Feels overly technical or academic for many readers
2. Dag (capitalized)
- Treats it as an Airflow-specific concept ("a Dag" = an Airflow
workflow)
- Reads more naturally in writing than all caps.
- Counterpoint: Neither a class name nor a standard word form, so it
can feel inconsistent
3. dag (lowercase)
- Reads like a common noun in Airflow vocabulary
- Matches Python identifiers (dag_id, dag.run_id) and blends cleanly
into text
- Counterpoint: Loses the visual link to the acronym and class name
If anyone has other proposals, please add them here and I'll include them
when the vote opens Monday. Please see the collapsed section for more
details and background.
Best,
Constance
--
Proposed framing for the vote:
- Option A: Prefer dag in docs; use DAG only when referring to the
class/import
- Option B: Prefer Dag in docs; use DAG only for the class/import
- Option C: Keep DAG as the standard everywhere (status quo)
Option with the most votes wins. You can vote between -1 to +1 for any of
the three options, and everyone will be encouraged to vote.
Summary of viewpoints so far (AI- generated):
- "dag" — clean, user-friendly, Pythonic, avoids shouting the acronym
- "DAG" — consistent with current APIs and historical context
- "Dag" — middle ground; distinguishes the concept from the acronym
while keeping it recognizable
Links:
- https://lists.apache.org/thread/lktrzqkzrpvc1cyctxz7zxfmc0fwtq2j
- https://lists.apache.org/thread/5fn1n188f99jspt627qhqsp2pznq545s
- https://lists.apache.org/thread/q7zdogwb76jko3vwz7tlsnl2cn3h3vg9
Constance
Re: [DISCUSS] Finalizing “DAG” terminology for docs and blog ("dag" vs "DAG" vs "Dag")
Posted by Jarek Potiuk <ja...@potiuk.com>.
> One other thing. I’m not sure that this is a procedural vote.
Code vote is what we do when merging particular changes (i.e. in our case
it's GitHub PR, in the case of SVN it's a patch someone proposes to apply)
. In this case `-1` = `require changes` (veto) on PR by the maintainer
blocks it.
In this case we are not voting on a single code change but on a general
rule (procedure) we are going to apply to future PRs. Thus - procedural
change.
IYou could argue that **any** decision on **any** vote leads to **some**
code modification eventually (for example when we discuss what should be a
process for release for example which results in a document that is then
merged.
Veto in PRs are reserved for cases when you see a particular code change
that **MUST NOT** be merged you **MUST** provide justification for that (
https://datatracker.ietf.org/doc/html/rfc2119 definitions).
J.
On Sat, Oct 18, 2025 at 2:17 AM Daniel Standish via dev <
dev@airflow.apache.org> wrote:
> One other thing. I’m not sure that this is a procedural vote. Because, what
> is the procedure we’re voting on? We’re essentially voting on a docs
> change. Are docs code? They kind of seem more like code than procedure.
> It’s almost like choosing a class name. Which would obviously be code.
> Anyway, it’s one thing that we should probably clarify.
>
> On Fri, Oct 17, 2025 at 9:35 AM Constance Martineau via dev <
> dev@airflow.apache.org> wrote:
>
> > To stir the pot a bit more, as someone pointed out, yes we have `DAG` but
> > we also have `dag` because of the decorator. So if we wanted to follow
> code
> > convention, is it `DAG` or `dag`?
> >
> > I really don't want to start using `Dag` in code but I guess it is
> pythonic
> > since it's technically a class name...
> >
> > Either way I can add it is as Option D: Prefer Dag in docs, use Dag for
> > class/import and alias DAG (for backcompat reasons)
> >
> > On Fri, Oct 17, 2025 at 10:34 AM Daniel Standish via dev <
> > dev@airflow.apache.org> wrote:
> >
> > > I’m not really proposing to rename to Dag in code.
> > >
> > > I’m mainly saying Dag in docs doesn’t feel right given that’s not the
> > > object in code.
> > >
> > > Just one man’s take.
> > >
> > > On Fri, Oct 17, 2025 at 4:12 AM Jarek Potiuk <ja...@potiuk.com> wrote:
> > >
> > > > > Old habits but I am fine with DAG and DAGs :)
> > > >
> > > > He, he: "we've always been doing it this way" to the fullest ;).
> > > >
> > > > But ... responding to Daniel's concern. I would be indeed for having
> > > those
> > > > two options:
> > > >
> > > > 2a) Dag in docs, DAG in code
> > > > 2b) Dag in docs, Dag in code (with DAG alias - no deprecation as it
> > will
> > > > break millions of Dags out there).
> > > >
> > > > That would be "proper" from the pure correctness point of view (DAG
> is
> > > not
> > > > a PEP-compliant name we have for the class).
> > > >
> > > > But only as long as we stress the implication and consequences so
> that
> > > > anyone voting realises what those practical consequences are.
> > > >
> > > > To be perfectly honest - even if I think it's a good idea to add this
> > > > option to vote, I am not in favour of it personally - precisely
> because
> > > of
> > > > the consequences.
> > > >
> > > > If we allow both `Dag` and `DAG` in the code the practical
> implications
> > > are
> > > > super messy IMHO. If people start using "Dag" in their code and
> publish
> > > it,
> > > > it will not work for pre-rename versions of Airflow, If we remove DAG
> > > > eventually - all the published code with DAG will not work for future
> > > > versions of Airflow. This will have a huge impact on issues raised
> by
> > > > users and is generally "messy" - the overall implication of such code
> > > > change will be that a number of users will consider Airflow Dags
> > broken.
> > > >
> > > > In this case I would strongly prefer to follow PEP-20, Python Zen:
> > > > https://peps.python.org/pep-0020/ - namely those two points:
> > > >
> > > > * There should be one-- and preferably only one --obvious way to do
> it.
> > > > * Although practicality beats purity.
> > > >
> > > > So - as long as we realise the consequences, possibly we should add
> the
> > > > option of "Dag in docs, Dag in the code" to vote on to address
> Daniel's
> > > > concerns.
> > > >
> > > > J.
> > > >
> > > > On Fri, Oct 17, 2025 at 12:43 PM Kaxil Naik <ka...@gmail.com>
> > wrote:
> > > >
> > > > > Old habits but I am fine with DAG and DAGs :)
> > > > >
> > > > > On Fri, 17 Oct 2025 at 07:18, Amogh Desai <am...@apache.org>
> > > wrote:
> > > > >
> > > > > > Not to explode this thread further, but "Dag" seems to be a good
> > > middle
> > > > > > ground to me for the reasons mentioned above by Constance and AI.
> > > > > >
> > > > > > And, "DAG" is the worst of all for me to use in day to day
> speech.
> > > > > >
> > > > > > Thanks & Regards,
> > > > > > Amogh Desai
> > > > > >
> > > > > >
> > > > > > On Fri, Oct 17, 2025 at 12:14 AM Daniel Standish via dev <
> > > > > > dev@airflow.apache.org> wrote:
> > > > > >
> > > > > > > It's not an easy call. But I think my take is that Dag would
> > make
> > > > > sense
> > > > > > if
> > > > > > > we rename the DAG object to Dag. But if we do not then it does
> > not
> > > > > seem
> > > > > > > right to style it as Dag.
> > > > > > >
> > > > > > > If we want to rename the actual object from DAG to Dag, then
> > sure.
> > > > > > >
> > > > > > > If we stay as DAG, I just like being able to write dag
> > midsentence
> > > > > > because
> > > > > > > that is how we do it normally when writing about dags. And
> DAGs
> > > > looks
> > > > > > > really awkward.
> > > > > > >
> > > > > > >
> > > > > > >
> > > > > > >
> > > > > > >
> > > > > > >
> > > > > > >
> > > > > > > On Thu, Oct 16, 2025 at 3:12 AM Amogh Desai <
> > amoghdesai@apache.org
> > > >
> > > > > > wrote:
> > > > > > >
> > > > > > > > Thanks for sending this notice, Constance.
> > > > > > > >
> > > > > > > > The older thread just blew up with too many opinions and
> > calling
> > > > > > > > a formal vote is the way to go.
> > > > > > > >
> > > > > > > > Thanks & Regards,
> > > > > > > > Amogh Desai
> > > > > > > >
> > > > > > > >
> > > > > > > > On Thu, Oct 16, 2025 at 1:08 AM Jarek Potiuk <
> jarek@potiuk.com
> > >
> > > > > wrote:
> > > > > > > >
> > > > > > > > > Very nice summary ! Thanks Constance :)
> > > > > > > > >
> > > > > > > > > On Wed, Oct 15, 2025 at 9:27 PM Constance Martineau via
> dev <
> > > > > > > > > dev@airflow.apache.org> wrote:
> > > > > > > > >
> > > > > > > > > > Reviving this discussion after the canceled vote:
> > > > > > > > > >
> > > > https://lists.apache.org/thread/q7zdogwb76jko3vwz7tlsnl2cn3h3vg9
> > > > > > > > > >
> > > > > > > > > > As mentioned earlier, I plan to *formally call a vote on
> > > > Monday*
> > > > > to
> > > > > > > > > > finalize how we refer to Airflow workflows in writing
> > (docs,
> > > > > > > tutorials,
> > > > > > > > > and
> > > > > > > > > > blog posts).
> > > > > > > > > >
> > > > > > > > > > This will *not* affect code (DAG and dag remain as-is in
> > APIs
> > > > and
> > > > > > > > > > decorators). The goal is to set a clear convention for
> > prose
> > > so
> > > > > > > > > > contributors and vendors can align their content
> > accordingly
> > > > > > > > > >
> > > > > > > > > > Why this matters: We’ve had inconsistent terminology
> across
> > > > docs
> > > > > > and
> > > > > > > > > > repeated PR debates over capitalization. Standardizing
> will
> > > > make
> > > > > > our
> > > > > > > > > > writing clearer, strengthen the Airflow brand, and give
> > > > external
> > > > > > > > > > stakeholders a single reference to follow.
> > > > > > > > > >
> > > > > > > > > > Options for standardization:
> > > > > > > > > >
> > > > > > > > > >
> > > > > > > > > > 1. DAG (all caps)
> > > > > > > > > > - Matches existing imports (from airflow.sdk import
> > > DAG)
> > > > > and
> > > > > > > the
> > > > > > > > > > broader ecosystem.
> > > > > > > > > > - Keeps a nod to the original meaning ("directed
> > > acyclic
> > > > > > > graph")
> > > > > > > > > > which still fits conceptually even if we later
> allow
> > > more
> > > > > > > > flexible
> > > > > > > > > > graph
> > > > > > > > > > types
> > > > > > > > > > - Counterpoint: Feels overly technical or academic
> > for
> > > > many
> > > > > > > > readers
> > > > > > > > > > 2. Dag (capitalized)
> > > > > > > > > > - Treats it as an Airflow-specific concept ("a
> Dag" =
> > > an
> > > > > > > Airflow
> > > > > > > > > > workflow)
> > > > > > > > > > - Reads more naturally in writing than all caps.
> > > > > > > > > > - Counterpoint: Neither a class name nor a standard
> > > word
> > > > > > form,
> > > > > > > so
> > > > > > > > > it
> > > > > > > > > > can feel inconsistent
> > > > > > > > > > 3. dag (lowercase)
> > > > > > > > > > - Reads like a common noun in Airflow vocabulary
> > > > > > > > > > - Matches Python identifiers (dag_id, dag.run_id)
> and
> > > > > blends
> > > > > > > > > cleanly
> > > > > > > > > > into text
> > > > > > > > > > - Counterpoint: Loses the visual link to the
> acronym
> > > and
> > > > > > class
> > > > > > > > name
> > > > > > > > > >
> > > > > > > > > > If anyone has other proposals, please add them here and
> > I'll
> > > > > > include
> > > > > > > > them
> > > > > > > > > > when the vote opens Monday. Please see the collapsed
> > section
> > > > for
> > > > > > more
> > > > > > > > > > details and background.
> > > > > > > > > >
> > > > > > > > > > Best,
> > > > > > > > > > Constance
> > > > > > > > > >
> > > > > > > > > > --
> > > > > > > > > >
> > > > > > > > > > Proposed framing for the vote:
> > > > > > > > > >
> > > > > > > > > > - Option A: Prefer dag in docs; use DAG only when
> > > referring
> > > > to
> > > > > > the
> > > > > > > > > > class/import
> > > > > > > > > > - Option B: Prefer Dag in docs; use DAG only for the
> > > > > > class/import
> > > > > > > > > > - Option C: Keep DAG as the standard everywhere
> (status
> > > quo)
> > > > > > > > > >
> > > > > > > > > > Option with the most votes wins. You can vote between -1
> to
> > > +1
> > > > > for
> > > > > > > any
> > > > > > > > of
> > > > > > > > > > the three options, and everyone will be encouraged to
> vote.
> > > > > > > > > >
> > > > > > > > > > Summary of viewpoints so far (AI- generated):
> > > > > > > > > >
> > > > > > > > > > - "dag" — clean, user-friendly, Pythonic, avoids
> > shouting
> > > > the
> > > > > > > > acronym
> > > > > > > > > > - "DAG" — consistent with current APIs and historical
> > > > context
> > > > > > > > > > - "Dag" — middle ground; distinguishes the concept
> from
> > > the
> > > > > > > acronym
> > > > > > > > > > while keeping it recognizable
> > > > > > > > > >
> > > > > > > > > > Links:
> > > > > > > > > >
> > > > > > > > > > -
> > > > > > >
> https://lists.apache.org/thread/lktrzqkzrpvc1cyctxz7zxfmc0fwtq2j
> > > > > > > > > > -
> > > > > > >
> https://lists.apache.org/thread/5fn1n188f99jspt627qhqsp2pznq545s
> > > > > > > > > > -
> > > > > > >
> https://lists.apache.org/thread/q7zdogwb76jko3vwz7tlsnl2cn3h3vg9
> > > > > > > > > >
> > > > > > > > > > Constance
> > > > > > > > > >
> > > > > > > > >
> > > > > > > >
> > > > > > >
> > > > > >
> > > > >
> > > >
> > >
> >
>
Re: [DISCUSS] Finalizing “DAG” terminology for docs and blog ("dag" vs "DAG" vs "Dag")
Posted by Daniel Standish via dev <de...@airflow.apache.org>.
One other thing. I’m not sure that this is a procedural vote. Because, what
is the procedure we’re voting on? We’re essentially voting on a docs
change. Are docs code? They kind of seem more like code than procedure.
It’s almost like choosing a class name. Which would obviously be code.
Anyway, it’s one thing that we should probably clarify.
On Fri, Oct 17, 2025 at 9:35 AM Constance Martineau via dev <
dev@airflow.apache.org> wrote:
> To stir the pot a bit more, as someone pointed out, yes we have `DAG` but
> we also have `dag` because of the decorator. So if we wanted to follow code
> convention, is it `DAG` or `dag`?
>
> I really don't want to start using `Dag` in code but I guess it is pythonic
> since it's technically a class name...
>
> Either way I can add it is as Option D: Prefer Dag in docs, use Dag for
> class/import and alias DAG (for backcompat reasons)
>
> On Fri, Oct 17, 2025 at 10:34 AM Daniel Standish via dev <
> dev@airflow.apache.org> wrote:
>
> > I’m not really proposing to rename to Dag in code.
> >
> > I’m mainly saying Dag in docs doesn’t feel right given that’s not the
> > object in code.
> >
> > Just one man’s take.
> >
> > On Fri, Oct 17, 2025 at 4:12 AM Jarek Potiuk <ja...@potiuk.com> wrote:
> >
> > > > Old habits but I am fine with DAG and DAGs :)
> > >
> > > He, he: "we've always been doing it this way" to the fullest ;).
> > >
> > > But ... responding to Daniel's concern. I would be indeed for having
> > those
> > > two options:
> > >
> > > 2a) Dag in docs, DAG in code
> > > 2b) Dag in docs, Dag in code (with DAG alias - no deprecation as it
> will
> > > break millions of Dags out there).
> > >
> > > That would be "proper" from the pure correctness point of view (DAG is
> > not
> > > a PEP-compliant name we have for the class).
> > >
> > > But only as long as we stress the implication and consequences so that
> > > anyone voting realises what those practical consequences are.
> > >
> > > To be perfectly honest - even if I think it's a good idea to add this
> > > option to vote, I am not in favour of it personally - precisely because
> > of
> > > the consequences.
> > >
> > > If we allow both `Dag` and `DAG` in the code the practical implications
> > are
> > > super messy IMHO. If people start using "Dag" in their code and publish
> > it,
> > > it will not work for pre-rename versions of Airflow, If we remove DAG
> > > eventually - all the published code with DAG will not work for future
> > > versions of Airflow. This will have a huge impact on issues raised by
> > > users and is generally "messy" - the overall implication of such code
> > > change will be that a number of users will consider Airflow Dags
> broken.
> > >
> > > In this case I would strongly prefer to follow PEP-20, Python Zen:
> > > https://peps.python.org/pep-0020/ - namely those two points:
> > >
> > > * There should be one-- and preferably only one --obvious way to do it.
> > > * Although practicality beats purity.
> > >
> > > So - as long as we realise the consequences, possibly we should add the
> > > option of "Dag in docs, Dag in the code" to vote on to address Daniel's
> > > concerns.
> > >
> > > J.
> > >
> > > On Fri, Oct 17, 2025 at 12:43 PM Kaxil Naik <ka...@gmail.com>
> wrote:
> > >
> > > > Old habits but I am fine with DAG and DAGs :)
> > > >
> > > > On Fri, 17 Oct 2025 at 07:18, Amogh Desai <am...@apache.org>
> > wrote:
> > > >
> > > > > Not to explode this thread further, but "Dag" seems to be a good
> > middle
> > > > > ground to me for the reasons mentioned above by Constance and AI.
> > > > >
> > > > > And, "DAG" is the worst of all for me to use in day to day speech.
> > > > >
> > > > > Thanks & Regards,
> > > > > Amogh Desai
> > > > >
> > > > >
> > > > > On Fri, Oct 17, 2025 at 12:14 AM Daniel Standish via dev <
> > > > > dev@airflow.apache.org> wrote:
> > > > >
> > > > > > It's not an easy call. But I think my take is that Dag would
> make
> > > > sense
> > > > > if
> > > > > > we rename the DAG object to Dag. But if we do not then it does
> not
> > > > seem
> > > > > > right to style it as Dag.
> > > > > >
> > > > > > If we want to rename the actual object from DAG to Dag, then
> sure.
> > > > > >
> > > > > > If we stay as DAG, I just like being able to write dag
> midsentence
> > > > > because
> > > > > > that is how we do it normally when writing about dags. And DAGs
> > > looks
> > > > > > really awkward.
> > > > > >
> > > > > >
> > > > > >
> > > > > >
> > > > > >
> > > > > >
> > > > > >
> > > > > > On Thu, Oct 16, 2025 at 3:12 AM Amogh Desai <
> amoghdesai@apache.org
> > >
> > > > > wrote:
> > > > > >
> > > > > > > Thanks for sending this notice, Constance.
> > > > > > >
> > > > > > > The older thread just blew up with too many opinions and
> calling
> > > > > > > a formal vote is the way to go.
> > > > > > >
> > > > > > > Thanks & Regards,
> > > > > > > Amogh Desai
> > > > > > >
> > > > > > >
> > > > > > > On Thu, Oct 16, 2025 at 1:08 AM Jarek Potiuk <jarek@potiuk.com
> >
> > > > wrote:
> > > > > > >
> > > > > > > > Very nice summary ! Thanks Constance :)
> > > > > > > >
> > > > > > > > On Wed, Oct 15, 2025 at 9:27 PM Constance Martineau via dev <
> > > > > > > > dev@airflow.apache.org> wrote:
> > > > > > > >
> > > > > > > > > Reviving this discussion after the canceled vote:
> > > > > > > > >
> > > https://lists.apache.org/thread/q7zdogwb76jko3vwz7tlsnl2cn3h3vg9
> > > > > > > > >
> > > > > > > > > As mentioned earlier, I plan to *formally call a vote on
> > > Monday*
> > > > to
> > > > > > > > > finalize how we refer to Airflow workflows in writing
> (docs,
> > > > > > tutorials,
> > > > > > > > and
> > > > > > > > > blog posts).
> > > > > > > > >
> > > > > > > > > This will *not* affect code (DAG and dag remain as-is in
> APIs
> > > and
> > > > > > > > > decorators). The goal is to set a clear convention for
> prose
> > so
> > > > > > > > > contributors and vendors can align their content
> accordingly
> > > > > > > > >
> > > > > > > > > Why this matters: We’ve had inconsistent terminology across
> > > docs
> > > > > and
> > > > > > > > > repeated PR debates over capitalization. Standardizing will
> > > make
> > > > > our
> > > > > > > > > writing clearer, strengthen the Airflow brand, and give
> > > external
> > > > > > > > > stakeholders a single reference to follow.
> > > > > > > > >
> > > > > > > > > Options for standardization:
> > > > > > > > >
> > > > > > > > >
> > > > > > > > > 1. DAG (all caps)
> > > > > > > > > - Matches existing imports (from airflow.sdk import
> > DAG)
> > > > and
> > > > > > the
> > > > > > > > > broader ecosystem.
> > > > > > > > > - Keeps a nod to the original meaning ("directed
> > acyclic
> > > > > > graph")
> > > > > > > > > which still fits conceptually even if we later allow
> > more
> > > > > > > flexible
> > > > > > > > > graph
> > > > > > > > > types
> > > > > > > > > - Counterpoint: Feels overly technical or academic
> for
> > > many
> > > > > > > readers
> > > > > > > > > 2. Dag (capitalized)
> > > > > > > > > - Treats it as an Airflow-specific concept ("a Dag" =
> > an
> > > > > > Airflow
> > > > > > > > > workflow)
> > > > > > > > > - Reads more naturally in writing than all caps.
> > > > > > > > > - Counterpoint: Neither a class name nor a standard
> > word
> > > > > form,
> > > > > > so
> > > > > > > > it
> > > > > > > > > can feel inconsistent
> > > > > > > > > 3. dag (lowercase)
> > > > > > > > > - Reads like a common noun in Airflow vocabulary
> > > > > > > > > - Matches Python identifiers (dag_id, dag.run_id) and
> > > > blends
> > > > > > > > cleanly
> > > > > > > > > into text
> > > > > > > > > - Counterpoint: Loses the visual link to the acronym
> > and
> > > > > class
> > > > > > > name
> > > > > > > > >
> > > > > > > > > If anyone has other proposals, please add them here and
> I'll
> > > > > include
> > > > > > > them
> > > > > > > > > when the vote opens Monday. Please see the collapsed
> section
> > > for
> > > > > more
> > > > > > > > > details and background.
> > > > > > > > >
> > > > > > > > > Best,
> > > > > > > > > Constance
> > > > > > > > >
> > > > > > > > > --
> > > > > > > > >
> > > > > > > > > Proposed framing for the vote:
> > > > > > > > >
> > > > > > > > > - Option A: Prefer dag in docs; use DAG only when
> > referring
> > > to
> > > > > the
> > > > > > > > > class/import
> > > > > > > > > - Option B: Prefer Dag in docs; use DAG only for the
> > > > > class/import
> > > > > > > > > - Option C: Keep DAG as the standard everywhere (status
> > quo)
> > > > > > > > >
> > > > > > > > > Option with the most votes wins. You can vote between -1 to
> > +1
> > > > for
> > > > > > any
> > > > > > > of
> > > > > > > > > the three options, and everyone will be encouraged to vote.
> > > > > > > > >
> > > > > > > > > Summary of viewpoints so far (AI- generated):
> > > > > > > > >
> > > > > > > > > - "dag" — clean, user-friendly, Pythonic, avoids
> shouting
> > > the
> > > > > > > acronym
> > > > > > > > > - "DAG" — consistent with current APIs and historical
> > > context
> > > > > > > > > - "Dag" — middle ground; distinguishes the concept from
> > the
> > > > > > acronym
> > > > > > > > > while keeping it recognizable
> > > > > > > > >
> > > > > > > > > Links:
> > > > > > > > >
> > > > > > > > > -
> > > > > > https://lists.apache.org/thread/lktrzqkzrpvc1cyctxz7zxfmc0fwtq2j
> > > > > > > > > -
> > > > > > https://lists.apache.org/thread/5fn1n188f99jspt627qhqsp2pznq545s
> > > > > > > > > -
> > > > > > https://lists.apache.org/thread/q7zdogwb76jko3vwz7tlsnl2cn3h3vg9
> > > > > > > > >
> > > > > > > > > Constance
> > > > > > > > >
> > > > > > > >
> > > > > > >
> > > > > >
> > > > >
> > > >
> > >
> >
>
Re: [DISCUSS] Finalizing “DAG” terminology for docs and blog ("dag" vs "DAG" vs "Dag")
Posted by Constance Martineau via dev <de...@airflow.apache.org>.
To stir the pot a bit more, as someone pointed out, yes we have `DAG` but
we also have `dag` because of the decorator. So if we wanted to follow code
convention, is it `DAG` or `dag`?
I really don't want to start using `Dag` in code but I guess it is pythonic
since it's technically a class name...
Either way I can add it is as Option D: Prefer Dag in docs, use Dag for
class/import and alias DAG (for backcompat reasons)
On Fri, Oct 17, 2025 at 10:34 AM Daniel Standish via dev <
dev@airflow.apache.org> wrote:
> I’m not really proposing to rename to Dag in code.
>
> I’m mainly saying Dag in docs doesn’t feel right given that’s not the
> object in code.
>
> Just one man’s take.
>
> On Fri, Oct 17, 2025 at 4:12 AM Jarek Potiuk <ja...@potiuk.com> wrote:
>
> > > Old habits but I am fine with DAG and DAGs :)
> >
> > He, he: "we've always been doing it this way" to the fullest ;).
> >
> > But ... responding to Daniel's concern. I would be indeed for having
> those
> > two options:
> >
> > 2a) Dag in docs, DAG in code
> > 2b) Dag in docs, Dag in code (with DAG alias - no deprecation as it will
> > break millions of Dags out there).
> >
> > That would be "proper" from the pure correctness point of view (DAG is
> not
> > a PEP-compliant name we have for the class).
> >
> > But only as long as we stress the implication and consequences so that
> > anyone voting realises what those practical consequences are.
> >
> > To be perfectly honest - even if I think it's a good idea to add this
> > option to vote, I am not in favour of it personally - precisely because
> of
> > the consequences.
> >
> > If we allow both `Dag` and `DAG` in the code the practical implications
> are
> > super messy IMHO. If people start using "Dag" in their code and publish
> it,
> > it will not work for pre-rename versions of Airflow, If we remove DAG
> > eventually - all the published code with DAG will not work for future
> > versions of Airflow. This will have a huge impact on issues raised by
> > users and is generally "messy" - the overall implication of such code
> > change will be that a number of users will consider Airflow Dags broken.
> >
> > In this case I would strongly prefer to follow PEP-20, Python Zen:
> > https://peps.python.org/pep-0020/ - namely those two points:
> >
> > * There should be one-- and preferably only one --obvious way to do it.
> > * Although practicality beats purity.
> >
> > So - as long as we realise the consequences, possibly we should add the
> > option of "Dag in docs, Dag in the code" to vote on to address Daniel's
> > concerns.
> >
> > J.
> >
> > On Fri, Oct 17, 2025 at 12:43 PM Kaxil Naik <ka...@gmail.com> wrote:
> >
> > > Old habits but I am fine with DAG and DAGs :)
> > >
> > > On Fri, 17 Oct 2025 at 07:18, Amogh Desai <am...@apache.org>
> wrote:
> > >
> > > > Not to explode this thread further, but "Dag" seems to be a good
> middle
> > > > ground to me for the reasons mentioned above by Constance and AI.
> > > >
> > > > And, "DAG" is the worst of all for me to use in day to day speech.
> > > >
> > > > Thanks & Regards,
> > > > Amogh Desai
> > > >
> > > >
> > > > On Fri, Oct 17, 2025 at 12:14 AM Daniel Standish via dev <
> > > > dev@airflow.apache.org> wrote:
> > > >
> > > > > It's not an easy call. But I think my take is that Dag would make
> > > sense
> > > > if
> > > > > we rename the DAG object to Dag. But if we do not then it does not
> > > seem
> > > > > right to style it as Dag.
> > > > >
> > > > > If we want to rename the actual object from DAG to Dag, then sure.
> > > > >
> > > > > If we stay as DAG, I just like being able to write dag midsentence
> > > > because
> > > > > that is how we do it normally when writing about dags. And DAGs
> > looks
> > > > > really awkward.
> > > > >
> > > > >
> > > > >
> > > > >
> > > > >
> > > > >
> > > > >
> > > > > On Thu, Oct 16, 2025 at 3:12 AM Amogh Desai <amoghdesai@apache.org
> >
> > > > wrote:
> > > > >
> > > > > > Thanks for sending this notice, Constance.
> > > > > >
> > > > > > The older thread just blew up with too many opinions and calling
> > > > > > a formal vote is the way to go.
> > > > > >
> > > > > > Thanks & Regards,
> > > > > > Amogh Desai
> > > > > >
> > > > > >
> > > > > > On Thu, Oct 16, 2025 at 1:08 AM Jarek Potiuk <ja...@potiuk.com>
> > > wrote:
> > > > > >
> > > > > > > Very nice summary ! Thanks Constance :)
> > > > > > >
> > > > > > > On Wed, Oct 15, 2025 at 9:27 PM Constance Martineau via dev <
> > > > > > > dev@airflow.apache.org> wrote:
> > > > > > >
> > > > > > > > Reviving this discussion after the canceled vote:
> > > > > > > >
> > https://lists.apache.org/thread/q7zdogwb76jko3vwz7tlsnl2cn3h3vg9
> > > > > > > >
> > > > > > > > As mentioned earlier, I plan to *formally call a vote on
> > Monday*
> > > to
> > > > > > > > finalize how we refer to Airflow workflows in writing (docs,
> > > > > tutorials,
> > > > > > > and
> > > > > > > > blog posts).
> > > > > > > >
> > > > > > > > This will *not* affect code (DAG and dag remain as-is in APIs
> > and
> > > > > > > > decorators). The goal is to set a clear convention for prose
> so
> > > > > > > > contributors and vendors can align their content accordingly
> > > > > > > >
> > > > > > > > Why this matters: We’ve had inconsistent terminology across
> > docs
> > > > and
> > > > > > > > repeated PR debates over capitalization. Standardizing will
> > make
> > > > our
> > > > > > > > writing clearer, strengthen the Airflow brand, and give
> > external
> > > > > > > > stakeholders a single reference to follow.
> > > > > > > >
> > > > > > > > Options for standardization:
> > > > > > > >
> > > > > > > >
> > > > > > > > 1. DAG (all caps)
> > > > > > > > - Matches existing imports (from airflow.sdk import
> DAG)
> > > and
> > > > > the
> > > > > > > > broader ecosystem.
> > > > > > > > - Keeps a nod to the original meaning ("directed
> acyclic
> > > > > graph")
> > > > > > > > which still fits conceptually even if we later allow
> more
> > > > > > flexible
> > > > > > > > graph
> > > > > > > > types
> > > > > > > > - Counterpoint: Feels overly technical or academic for
> > many
> > > > > > readers
> > > > > > > > 2. Dag (capitalized)
> > > > > > > > - Treats it as an Airflow-specific concept ("a Dag" =
> an
> > > > > Airflow
> > > > > > > > workflow)
> > > > > > > > - Reads more naturally in writing than all caps.
> > > > > > > > - Counterpoint: Neither a class name nor a standard
> word
> > > > form,
> > > > > so
> > > > > > > it
> > > > > > > > can feel inconsistent
> > > > > > > > 3. dag (lowercase)
> > > > > > > > - Reads like a common noun in Airflow vocabulary
> > > > > > > > - Matches Python identifiers (dag_id, dag.run_id) and
> > > blends
> > > > > > > cleanly
> > > > > > > > into text
> > > > > > > > - Counterpoint: Loses the visual link to the acronym
> and
> > > > class
> > > > > > name
> > > > > > > >
> > > > > > > > If anyone has other proposals, please add them here and I'll
> > > > include
> > > > > > them
> > > > > > > > when the vote opens Monday. Please see the collapsed section
> > for
> > > > more
> > > > > > > > details and background.
> > > > > > > >
> > > > > > > > Best,
> > > > > > > > Constance
> > > > > > > >
> > > > > > > > --
> > > > > > > >
> > > > > > > > Proposed framing for the vote:
> > > > > > > >
> > > > > > > > - Option A: Prefer dag in docs; use DAG only when
> referring
> > to
> > > > the
> > > > > > > > class/import
> > > > > > > > - Option B: Prefer Dag in docs; use DAG only for the
> > > > class/import
> > > > > > > > - Option C: Keep DAG as the standard everywhere (status
> quo)
> > > > > > > >
> > > > > > > > Option with the most votes wins. You can vote between -1 to
> +1
> > > for
> > > > > any
> > > > > > of
> > > > > > > > the three options, and everyone will be encouraged to vote.
> > > > > > > >
> > > > > > > > Summary of viewpoints so far (AI- generated):
> > > > > > > >
> > > > > > > > - "dag" — clean, user-friendly, Pythonic, avoids shouting
> > the
> > > > > > acronym
> > > > > > > > - "DAG" — consistent with current APIs and historical
> > context
> > > > > > > > - "Dag" — middle ground; distinguishes the concept from
> the
> > > > > acronym
> > > > > > > > while keeping it recognizable
> > > > > > > >
> > > > > > > > Links:
> > > > > > > >
> > > > > > > > -
> > > > > https://lists.apache.org/thread/lktrzqkzrpvc1cyctxz7zxfmc0fwtq2j
> > > > > > > > -
> > > > > https://lists.apache.org/thread/5fn1n188f99jspt627qhqsp2pznq545s
> > > > > > > > -
> > > > > https://lists.apache.org/thread/q7zdogwb76jko3vwz7tlsnl2cn3h3vg9
> > > > > > > >
> > > > > > > > Constance
> > > > > > > >
> > > > > > >
> > > > > >
> > > > >
> > > >
> > >
> >
>
Re: [DISCUSS] Finalizing “DAG” terminology for docs and blog ("dag" vs "DAG" vs "Dag")
Posted by Daniel Standish via dev <de...@airflow.apache.org>.
I’m not really proposing to rename to Dag in code.
I’m mainly saying Dag in docs doesn’t feel right given that’s not the
object in code.
Just one man’s take.
On Fri, Oct 17, 2025 at 4:12 AM Jarek Potiuk <ja...@potiuk.com> wrote:
> > Old habits but I am fine with DAG and DAGs :)
>
> He, he: "we've always been doing it this way" to the fullest ;).
>
> But ... responding to Daniel's concern. I would be indeed for having those
> two options:
>
> 2a) Dag in docs, DAG in code
> 2b) Dag in docs, Dag in code (with DAG alias - no deprecation as it will
> break millions of Dags out there).
>
> That would be "proper" from the pure correctness point of view (DAG is not
> a PEP-compliant name we have for the class).
>
> But only as long as we stress the implication and consequences so that
> anyone voting realises what those practical consequences are.
>
> To be perfectly honest - even if I think it's a good idea to add this
> option to vote, I am not in favour of it personally - precisely because of
> the consequences.
>
> If we allow both `Dag` and `DAG` in the code the practical implications are
> super messy IMHO. If people start using "Dag" in their code and publish it,
> it will not work for pre-rename versions of Airflow, If we remove DAG
> eventually - all the published code with DAG will not work for future
> versions of Airflow. This will have a huge impact on issues raised by
> users and is generally "messy" - the overall implication of such code
> change will be that a number of users will consider Airflow Dags broken.
>
> In this case I would strongly prefer to follow PEP-20, Python Zen:
> https://peps.python.org/pep-0020/ - namely those two points:
>
> * There should be one-- and preferably only one --obvious way to do it.
> * Although practicality beats purity.
>
> So - as long as we realise the consequences, possibly we should add the
> option of "Dag in docs, Dag in the code" to vote on to address Daniel's
> concerns.
>
> J.
>
> On Fri, Oct 17, 2025 at 12:43 PM Kaxil Naik <ka...@gmail.com> wrote:
>
> > Old habits but I am fine with DAG and DAGs :)
> >
> > On Fri, 17 Oct 2025 at 07:18, Amogh Desai <am...@apache.org> wrote:
> >
> > > Not to explode this thread further, but "Dag" seems to be a good middle
> > > ground to me for the reasons mentioned above by Constance and AI.
> > >
> > > And, "DAG" is the worst of all for me to use in day to day speech.
> > >
> > > Thanks & Regards,
> > > Amogh Desai
> > >
> > >
> > > On Fri, Oct 17, 2025 at 12:14 AM Daniel Standish via dev <
> > > dev@airflow.apache.org> wrote:
> > >
> > > > It's not an easy call. But I think my take is that Dag would make
> > sense
> > > if
> > > > we rename the DAG object to Dag. But if we do not then it does not
> > seem
> > > > right to style it as Dag.
> > > >
> > > > If we want to rename the actual object from DAG to Dag, then sure.
> > > >
> > > > If we stay as DAG, I just like being able to write dag midsentence
> > > because
> > > > that is how we do it normally when writing about dags. And DAGs
> looks
> > > > really awkward.
> > > >
> > > >
> > > >
> > > >
> > > >
> > > >
> > > >
> > > > On Thu, Oct 16, 2025 at 3:12 AM Amogh Desai <am...@apache.org>
> > > wrote:
> > > >
> > > > > Thanks for sending this notice, Constance.
> > > > >
> > > > > The older thread just blew up with too many opinions and calling
> > > > > a formal vote is the way to go.
> > > > >
> > > > > Thanks & Regards,
> > > > > Amogh Desai
> > > > >
> > > > >
> > > > > On Thu, Oct 16, 2025 at 1:08 AM Jarek Potiuk <ja...@potiuk.com>
> > wrote:
> > > > >
> > > > > > Very nice summary ! Thanks Constance :)
> > > > > >
> > > > > > On Wed, Oct 15, 2025 at 9:27 PM Constance Martineau via dev <
> > > > > > dev@airflow.apache.org> wrote:
> > > > > >
> > > > > > > Reviving this discussion after the canceled vote:
> > > > > > >
> https://lists.apache.org/thread/q7zdogwb76jko3vwz7tlsnl2cn3h3vg9
> > > > > > >
> > > > > > > As mentioned earlier, I plan to *formally call a vote on
> Monday*
> > to
> > > > > > > finalize how we refer to Airflow workflows in writing (docs,
> > > > tutorials,
> > > > > > and
> > > > > > > blog posts).
> > > > > > >
> > > > > > > This will *not* affect code (DAG and dag remain as-is in APIs
> and
> > > > > > > decorators). The goal is to set a clear convention for prose so
> > > > > > > contributors and vendors can align their content accordingly
> > > > > > >
> > > > > > > Why this matters: We’ve had inconsistent terminology across
> docs
> > > and
> > > > > > > repeated PR debates over capitalization. Standardizing will
> make
> > > our
> > > > > > > writing clearer, strengthen the Airflow brand, and give
> external
> > > > > > > stakeholders a single reference to follow.
> > > > > > >
> > > > > > > Options for standardization:
> > > > > > >
> > > > > > >
> > > > > > > 1. DAG (all caps)
> > > > > > > - Matches existing imports (from airflow.sdk import DAG)
> > and
> > > > the
> > > > > > > broader ecosystem.
> > > > > > > - Keeps a nod to the original meaning ("directed acyclic
> > > > graph")
> > > > > > > which still fits conceptually even if we later allow more
> > > > > flexible
> > > > > > > graph
> > > > > > > types
> > > > > > > - Counterpoint: Feels overly technical or academic for
> many
> > > > > readers
> > > > > > > 2. Dag (capitalized)
> > > > > > > - Treats it as an Airflow-specific concept ("a Dag" = an
> > > > Airflow
> > > > > > > workflow)
> > > > > > > - Reads more naturally in writing than all caps.
> > > > > > > - Counterpoint: Neither a class name nor a standard word
> > > form,
> > > > so
> > > > > > it
> > > > > > > can feel inconsistent
> > > > > > > 3. dag (lowercase)
> > > > > > > - Reads like a common noun in Airflow vocabulary
> > > > > > > - Matches Python identifiers (dag_id, dag.run_id) and
> > blends
> > > > > > cleanly
> > > > > > > into text
> > > > > > > - Counterpoint: Loses the visual link to the acronym and
> > > class
> > > > > name
> > > > > > >
> > > > > > > If anyone has other proposals, please add them here and I'll
> > > include
> > > > > them
> > > > > > > when the vote opens Monday. Please see the collapsed section
> for
> > > more
> > > > > > > details and background.
> > > > > > >
> > > > > > > Best,
> > > > > > > Constance
> > > > > > >
> > > > > > > --
> > > > > > >
> > > > > > > Proposed framing for the vote:
> > > > > > >
> > > > > > > - Option A: Prefer dag in docs; use DAG only when referring
> to
> > > the
> > > > > > > class/import
> > > > > > > - Option B: Prefer Dag in docs; use DAG only for the
> > > class/import
> > > > > > > - Option C: Keep DAG as the standard everywhere (status quo)
> > > > > > >
> > > > > > > Option with the most votes wins. You can vote between -1 to +1
> > for
> > > > any
> > > > > of
> > > > > > > the three options, and everyone will be encouraged to vote.
> > > > > > >
> > > > > > > Summary of viewpoints so far (AI- generated):
> > > > > > >
> > > > > > > - "dag" — clean, user-friendly, Pythonic, avoids shouting
> the
> > > > > acronym
> > > > > > > - "DAG" — consistent with current APIs and historical
> context
> > > > > > > - "Dag" — middle ground; distinguishes the concept from the
> > > > acronym
> > > > > > > while keeping it recognizable
> > > > > > >
> > > > > > > Links:
> > > > > > >
> > > > > > > -
> > > > https://lists.apache.org/thread/lktrzqkzrpvc1cyctxz7zxfmc0fwtq2j
> > > > > > > -
> > > > https://lists.apache.org/thread/5fn1n188f99jspt627qhqsp2pznq545s
> > > > > > > -
> > > > https://lists.apache.org/thread/q7zdogwb76jko3vwz7tlsnl2cn3h3vg9
> > > > > > >
> > > > > > > Constance
> > > > > > >
> > > > > >
> > > > >
> > > >
> > >
> >
>
Re: [DISCUSS] Finalizing “DAG” terminology for docs and blog ("dag" vs "DAG" vs "Dag")
Posted by Jarek Potiuk <ja...@potiuk.com>.
> Old habits but I am fine with DAG and DAGs :)
He, he: "we've always been doing it this way" to the fullest ;).
But ... responding to Daniel's concern. I would be indeed for having those
two options:
2a) Dag in docs, DAG in code
2b) Dag in docs, Dag in code (with DAG alias - no deprecation as it will
break millions of Dags out there).
That would be "proper" from the pure correctness point of view (DAG is not
a PEP-compliant name we have for the class).
But only as long as we stress the implication and consequences so that
anyone voting realises what those practical consequences are.
To be perfectly honest - even if I think it's a good idea to add this
option to vote, I am not in favour of it personally - precisely because of
the consequences.
If we allow both `Dag` and `DAG` in the code the practical implications are
super messy IMHO. If people start using "Dag" in their code and publish it,
it will not work for pre-rename versions of Airflow, If we remove DAG
eventually - all the published code with DAG will not work for future
versions of Airflow. This will have a huge impact on issues raised by
users and is generally "messy" - the overall implication of such code
change will be that a number of users will consider Airflow Dags broken.
In this case I would strongly prefer to follow PEP-20, Python Zen:
https://peps.python.org/pep-0020/ - namely those two points:
* There should be one-- and preferably only one --obvious way to do it.
* Although practicality beats purity.
So - as long as we realise the consequences, possibly we should add the
option of "Dag in docs, Dag in the code" to vote on to address Daniel's
concerns.
J.
On Fri, Oct 17, 2025 at 12:43 PM Kaxil Naik <ka...@gmail.com> wrote:
> Old habits but I am fine with DAG and DAGs :)
>
> On Fri, 17 Oct 2025 at 07:18, Amogh Desai <am...@apache.org> wrote:
>
> > Not to explode this thread further, but "Dag" seems to be a good middle
> > ground to me for the reasons mentioned above by Constance and AI.
> >
> > And, "DAG" is the worst of all for me to use in day to day speech.
> >
> > Thanks & Regards,
> > Amogh Desai
> >
> >
> > On Fri, Oct 17, 2025 at 12:14 AM Daniel Standish via dev <
> > dev@airflow.apache.org> wrote:
> >
> > > It's not an easy call. But I think my take is that Dag would make
> sense
> > if
> > > we rename the DAG object to Dag. But if we do not then it does not
> seem
> > > right to style it as Dag.
> > >
> > > If we want to rename the actual object from DAG to Dag, then sure.
> > >
> > > If we stay as DAG, I just like being able to write dag midsentence
> > because
> > > that is how we do it normally when writing about dags. And DAGs looks
> > > really awkward.
> > >
> > >
> > >
> > >
> > >
> > >
> > >
> > > On Thu, Oct 16, 2025 at 3:12 AM Amogh Desai <am...@apache.org>
> > wrote:
> > >
> > > > Thanks for sending this notice, Constance.
> > > >
> > > > The older thread just blew up with too many opinions and calling
> > > > a formal vote is the way to go.
> > > >
> > > > Thanks & Regards,
> > > > Amogh Desai
> > > >
> > > >
> > > > On Thu, Oct 16, 2025 at 1:08 AM Jarek Potiuk <ja...@potiuk.com>
> wrote:
> > > >
> > > > > Very nice summary ! Thanks Constance :)
> > > > >
> > > > > On Wed, Oct 15, 2025 at 9:27 PM Constance Martineau via dev <
> > > > > dev@airflow.apache.org> wrote:
> > > > >
> > > > > > Reviving this discussion after the canceled vote:
> > > > > > https://lists.apache.org/thread/q7zdogwb76jko3vwz7tlsnl2cn3h3vg9
> > > > > >
> > > > > > As mentioned earlier, I plan to *formally call a vote on Monday*
> to
> > > > > > finalize how we refer to Airflow workflows in writing (docs,
> > > tutorials,
> > > > > and
> > > > > > blog posts).
> > > > > >
> > > > > > This will *not* affect code (DAG and dag remain as-is in APIs and
> > > > > > decorators). The goal is to set a clear convention for prose so
> > > > > > contributors and vendors can align their content accordingly
> > > > > >
> > > > > > Why this matters: We’ve had inconsistent terminology across docs
> > and
> > > > > > repeated PR debates over capitalization. Standardizing will make
> > our
> > > > > > writing clearer, strengthen the Airflow brand, and give external
> > > > > > stakeholders a single reference to follow.
> > > > > >
> > > > > > Options for standardization:
> > > > > >
> > > > > >
> > > > > > 1. DAG (all caps)
> > > > > > - Matches existing imports (from airflow.sdk import DAG)
> and
> > > the
> > > > > > broader ecosystem.
> > > > > > - Keeps a nod to the original meaning ("directed acyclic
> > > graph")
> > > > > > which still fits conceptually even if we later allow more
> > > > flexible
> > > > > > graph
> > > > > > types
> > > > > > - Counterpoint: Feels overly technical or academic for many
> > > > readers
> > > > > > 2. Dag (capitalized)
> > > > > > - Treats it as an Airflow-specific concept ("a Dag" = an
> > > Airflow
> > > > > > workflow)
> > > > > > - Reads more naturally in writing than all caps.
> > > > > > - Counterpoint: Neither a class name nor a standard word
> > form,
> > > so
> > > > > it
> > > > > > can feel inconsistent
> > > > > > 3. dag (lowercase)
> > > > > > - Reads like a common noun in Airflow vocabulary
> > > > > > - Matches Python identifiers (dag_id, dag.run_id) and
> blends
> > > > > cleanly
> > > > > > into text
> > > > > > - Counterpoint: Loses the visual link to the acronym and
> > class
> > > > name
> > > > > >
> > > > > > If anyone has other proposals, please add them here and I'll
> > include
> > > > them
> > > > > > when the vote opens Monday. Please see the collapsed section for
> > more
> > > > > > details and background.
> > > > > >
> > > > > > Best,
> > > > > > Constance
> > > > > >
> > > > > > --
> > > > > >
> > > > > > Proposed framing for the vote:
> > > > > >
> > > > > > - Option A: Prefer dag in docs; use DAG only when referring to
> > the
> > > > > > class/import
> > > > > > - Option B: Prefer Dag in docs; use DAG only for the
> > class/import
> > > > > > - Option C: Keep DAG as the standard everywhere (status quo)
> > > > > >
> > > > > > Option with the most votes wins. You can vote between -1 to +1
> for
> > > any
> > > > of
> > > > > > the three options, and everyone will be encouraged to vote.
> > > > > >
> > > > > > Summary of viewpoints so far (AI- generated):
> > > > > >
> > > > > > - "dag" — clean, user-friendly, Pythonic, avoids shouting the
> > > > acronym
> > > > > > - "DAG" — consistent with current APIs and historical context
> > > > > > - "Dag" — middle ground; distinguishes the concept from the
> > > acronym
> > > > > > while keeping it recognizable
> > > > > >
> > > > > > Links:
> > > > > >
> > > > > > -
> > > https://lists.apache.org/thread/lktrzqkzrpvc1cyctxz7zxfmc0fwtq2j
> > > > > > -
> > > https://lists.apache.org/thread/5fn1n188f99jspt627qhqsp2pznq545s
> > > > > > -
> > > https://lists.apache.org/thread/q7zdogwb76jko3vwz7tlsnl2cn3h3vg9
> > > > > >
> > > > > > Constance
> > > > > >
> > > > >
> > > >
> > >
> >
>
Re: [DISCUSS] Finalizing “DAG” terminology for docs and blog ("dag" vs "DAG" vs "Dag")
Posted by Kaxil Naik <ka...@gmail.com>.
Old habits but I am fine with DAG and DAGs :)
On Fri, 17 Oct 2025 at 07:18, Amogh Desai <am...@apache.org> wrote:
> Not to explode this thread further, but "Dag" seems to be a good middle
> ground to me for the reasons mentioned above by Constance and AI.
>
> And, "DAG" is the worst of all for me to use in day to day speech.
>
> Thanks & Regards,
> Amogh Desai
>
>
> On Fri, Oct 17, 2025 at 12:14 AM Daniel Standish via dev <
> dev@airflow.apache.org> wrote:
>
> > It's not an easy call. But I think my take is that Dag would make sense
> if
> > we rename the DAG object to Dag. But if we do not then it does not seem
> > right to style it as Dag.
> >
> > If we want to rename the actual object from DAG to Dag, then sure.
> >
> > If we stay as DAG, I just like being able to write dag midsentence
> because
> > that is how we do it normally when writing about dags. And DAGs looks
> > really awkward.
> >
> >
> >
> >
> >
> >
> >
> > On Thu, Oct 16, 2025 at 3:12 AM Amogh Desai <am...@apache.org>
> wrote:
> >
> > > Thanks for sending this notice, Constance.
> > >
> > > The older thread just blew up with too many opinions and calling
> > > a formal vote is the way to go.
> > >
> > > Thanks & Regards,
> > > Amogh Desai
> > >
> > >
> > > On Thu, Oct 16, 2025 at 1:08 AM Jarek Potiuk <ja...@potiuk.com> wrote:
> > >
> > > > Very nice summary ! Thanks Constance :)
> > > >
> > > > On Wed, Oct 15, 2025 at 9:27 PM Constance Martineau via dev <
> > > > dev@airflow.apache.org> wrote:
> > > >
> > > > > Reviving this discussion after the canceled vote:
> > > > > https://lists.apache.org/thread/q7zdogwb76jko3vwz7tlsnl2cn3h3vg9
> > > > >
> > > > > As mentioned earlier, I plan to *formally call a vote on Monday* to
> > > > > finalize how we refer to Airflow workflows in writing (docs,
> > tutorials,
> > > > and
> > > > > blog posts).
> > > > >
> > > > > This will *not* affect code (DAG and dag remain as-is in APIs and
> > > > > decorators). The goal is to set a clear convention for prose so
> > > > > contributors and vendors can align their content accordingly
> > > > >
> > > > > Why this matters: We’ve had inconsistent terminology across docs
> and
> > > > > repeated PR debates over capitalization. Standardizing will make
> our
> > > > > writing clearer, strengthen the Airflow brand, and give external
> > > > > stakeholders a single reference to follow.
> > > > >
> > > > > Options for standardization:
> > > > >
> > > > >
> > > > > 1. DAG (all caps)
> > > > > - Matches existing imports (from airflow.sdk import DAG) and
> > the
> > > > > broader ecosystem.
> > > > > - Keeps a nod to the original meaning ("directed acyclic
> > graph")
> > > > > which still fits conceptually even if we later allow more
> > > flexible
> > > > > graph
> > > > > types
> > > > > - Counterpoint: Feels overly technical or academic for many
> > > readers
> > > > > 2. Dag (capitalized)
> > > > > - Treats it as an Airflow-specific concept ("a Dag" = an
> > Airflow
> > > > > workflow)
> > > > > - Reads more naturally in writing than all caps.
> > > > > - Counterpoint: Neither a class name nor a standard word
> form,
> > so
> > > > it
> > > > > can feel inconsistent
> > > > > 3. dag (lowercase)
> > > > > - Reads like a common noun in Airflow vocabulary
> > > > > - Matches Python identifiers (dag_id, dag.run_id) and blends
> > > > cleanly
> > > > > into text
> > > > > - Counterpoint: Loses the visual link to the acronym and
> class
> > > name
> > > > >
> > > > > If anyone has other proposals, please add them here and I'll
> include
> > > them
> > > > > when the vote opens Monday. Please see the collapsed section for
> more
> > > > > details and background.
> > > > >
> > > > > Best,
> > > > > Constance
> > > > >
> > > > > --
> > > > >
> > > > > Proposed framing for the vote:
> > > > >
> > > > > - Option A: Prefer dag in docs; use DAG only when referring to
> the
> > > > > class/import
> > > > > - Option B: Prefer Dag in docs; use DAG only for the
> class/import
> > > > > - Option C: Keep DAG as the standard everywhere (status quo)
> > > > >
> > > > > Option with the most votes wins. You can vote between -1 to +1 for
> > any
> > > of
> > > > > the three options, and everyone will be encouraged to vote.
> > > > >
> > > > > Summary of viewpoints so far (AI- generated):
> > > > >
> > > > > - "dag" — clean, user-friendly, Pythonic, avoids shouting the
> > > acronym
> > > > > - "DAG" — consistent with current APIs and historical context
> > > > > - "Dag" — middle ground; distinguishes the concept from the
> > acronym
> > > > > while keeping it recognizable
> > > > >
> > > > > Links:
> > > > >
> > > > > -
> > https://lists.apache.org/thread/lktrzqkzrpvc1cyctxz7zxfmc0fwtq2j
> > > > > -
> > https://lists.apache.org/thread/5fn1n188f99jspt627qhqsp2pznq545s
> > > > > -
> > https://lists.apache.org/thread/q7zdogwb76jko3vwz7tlsnl2cn3h3vg9
> > > > >
> > > > > Constance
> > > > >
> > > >
> > >
> >
>
Re: [DISCUSS] Finalizing “DAG” terminology for docs and blog ("dag" vs "DAG" vs "Dag")
Posted by Amogh Desai <am...@apache.org>.
Not to explode this thread further, but "Dag" seems to be a good middle
ground to me for the reasons mentioned above by Constance and AI.
And, "DAG" is the worst of all for me to use in day to day speech.
Thanks & Regards,
Amogh Desai
On Fri, Oct 17, 2025 at 12:14 AM Daniel Standish via dev <
dev@airflow.apache.org> wrote:
> It's not an easy call. But I think my take is that Dag would make sense if
> we rename the DAG object to Dag. But if we do not then it does not seem
> right to style it as Dag.
>
> If we want to rename the actual object from DAG to Dag, then sure.
>
> If we stay as DAG, I just like being able to write dag midsentence because
> that is how we do it normally when writing about dags. And DAGs looks
> really awkward.
>
>
>
>
>
>
>
> On Thu, Oct 16, 2025 at 3:12 AM Amogh Desai <am...@apache.org> wrote:
>
> > Thanks for sending this notice, Constance.
> >
> > The older thread just blew up with too many opinions and calling
> > a formal vote is the way to go.
> >
> > Thanks & Regards,
> > Amogh Desai
> >
> >
> > On Thu, Oct 16, 2025 at 1:08 AM Jarek Potiuk <ja...@potiuk.com> wrote:
> >
> > > Very nice summary ! Thanks Constance :)
> > >
> > > On Wed, Oct 15, 2025 at 9:27 PM Constance Martineau via dev <
> > > dev@airflow.apache.org> wrote:
> > >
> > > > Reviving this discussion after the canceled vote:
> > > > https://lists.apache.org/thread/q7zdogwb76jko3vwz7tlsnl2cn3h3vg9
> > > >
> > > > As mentioned earlier, I plan to *formally call a vote on Monday* to
> > > > finalize how we refer to Airflow workflows in writing (docs,
> tutorials,
> > > and
> > > > blog posts).
> > > >
> > > > This will *not* affect code (DAG and dag remain as-is in APIs and
> > > > decorators). The goal is to set a clear convention for prose so
> > > > contributors and vendors can align their content accordingly
> > > >
> > > > Why this matters: We’ve had inconsistent terminology across docs and
> > > > repeated PR debates over capitalization. Standardizing will make our
> > > > writing clearer, strengthen the Airflow brand, and give external
> > > > stakeholders a single reference to follow.
> > > >
> > > > Options for standardization:
> > > >
> > > >
> > > > 1. DAG (all caps)
> > > > - Matches existing imports (from airflow.sdk import DAG) and
> the
> > > > broader ecosystem.
> > > > - Keeps a nod to the original meaning ("directed acyclic
> graph")
> > > > which still fits conceptually even if we later allow more
> > flexible
> > > > graph
> > > > types
> > > > - Counterpoint: Feels overly technical or academic for many
> > readers
> > > > 2. Dag (capitalized)
> > > > - Treats it as an Airflow-specific concept ("a Dag" = an
> Airflow
> > > > workflow)
> > > > - Reads more naturally in writing than all caps.
> > > > - Counterpoint: Neither a class name nor a standard word form,
> so
> > > it
> > > > can feel inconsistent
> > > > 3. dag (lowercase)
> > > > - Reads like a common noun in Airflow vocabulary
> > > > - Matches Python identifiers (dag_id, dag.run_id) and blends
> > > cleanly
> > > > into text
> > > > - Counterpoint: Loses the visual link to the acronym and class
> > name
> > > >
> > > > If anyone has other proposals, please add them here and I'll include
> > them
> > > > when the vote opens Monday. Please see the collapsed section for more
> > > > details and background.
> > > >
> > > > Best,
> > > > Constance
> > > >
> > > > --
> > > >
> > > > Proposed framing for the vote:
> > > >
> > > > - Option A: Prefer dag in docs; use DAG only when referring to the
> > > > class/import
> > > > - Option B: Prefer Dag in docs; use DAG only for the class/import
> > > > - Option C: Keep DAG as the standard everywhere (status quo)
> > > >
> > > > Option with the most votes wins. You can vote between -1 to +1 for
> any
> > of
> > > > the three options, and everyone will be encouraged to vote.
> > > >
> > > > Summary of viewpoints so far (AI- generated):
> > > >
> > > > - "dag" — clean, user-friendly, Pythonic, avoids shouting the
> > acronym
> > > > - "DAG" — consistent with current APIs and historical context
> > > > - "Dag" — middle ground; distinguishes the concept from the
> acronym
> > > > while keeping it recognizable
> > > >
> > > > Links:
> > > >
> > > > -
> https://lists.apache.org/thread/lktrzqkzrpvc1cyctxz7zxfmc0fwtq2j
> > > > -
> https://lists.apache.org/thread/5fn1n188f99jspt627qhqsp2pznq545s
> > > > -
> https://lists.apache.org/thread/q7zdogwb76jko3vwz7tlsnl2cn3h3vg9
> > > >
> > > > Constance
> > > >
> > >
> >
>
Re: [DISCUSS] Finalizing “DAG” terminology for docs and blog ("dag" vs "DAG" vs "Dag")
Posted by Daniel Standish via dev <de...@airflow.apache.org>.
It's not an easy call. But I think my take is that Dag would make sense if
we rename the DAG object to Dag. But if we do not then it does not seem
right to style it as Dag.
If we want to rename the actual object from DAG to Dag, then sure.
If we stay as DAG, I just like being able to write dag midsentence because
that is how we do it normally when writing about dags. And DAGs looks
really awkward.
On Thu, Oct 16, 2025 at 3:12 AM Amogh Desai <am...@apache.org> wrote:
> Thanks for sending this notice, Constance.
>
> The older thread just blew up with too many opinions and calling
> a formal vote is the way to go.
>
> Thanks & Regards,
> Amogh Desai
>
>
> On Thu, Oct 16, 2025 at 1:08 AM Jarek Potiuk <ja...@potiuk.com> wrote:
>
> > Very nice summary ! Thanks Constance :)
> >
> > On Wed, Oct 15, 2025 at 9:27 PM Constance Martineau via dev <
> > dev@airflow.apache.org> wrote:
> >
> > > Reviving this discussion after the canceled vote:
> > > https://lists.apache.org/thread/q7zdogwb76jko3vwz7tlsnl2cn3h3vg9
> > >
> > > As mentioned earlier, I plan to *formally call a vote on Monday* to
> > > finalize how we refer to Airflow workflows in writing (docs, tutorials,
> > and
> > > blog posts).
> > >
> > > This will *not* affect code (DAG and dag remain as-is in APIs and
> > > decorators). The goal is to set a clear convention for prose so
> > > contributors and vendors can align their content accordingly
> > >
> > > Why this matters: We’ve had inconsistent terminology across docs and
> > > repeated PR debates over capitalization. Standardizing will make our
> > > writing clearer, strengthen the Airflow brand, and give external
> > > stakeholders a single reference to follow.
> > >
> > > Options for standardization:
> > >
> > >
> > > 1. DAG (all caps)
> > > - Matches existing imports (from airflow.sdk import DAG) and the
> > > broader ecosystem.
> > > - Keeps a nod to the original meaning ("directed acyclic graph")
> > > which still fits conceptually even if we later allow more
> flexible
> > > graph
> > > types
> > > - Counterpoint: Feels overly technical or academic for many
> readers
> > > 2. Dag (capitalized)
> > > - Treats it as an Airflow-specific concept ("a Dag" = an Airflow
> > > workflow)
> > > - Reads more naturally in writing than all caps.
> > > - Counterpoint: Neither a class name nor a standard word form, so
> > it
> > > can feel inconsistent
> > > 3. dag (lowercase)
> > > - Reads like a common noun in Airflow vocabulary
> > > - Matches Python identifiers (dag_id, dag.run_id) and blends
> > cleanly
> > > into text
> > > - Counterpoint: Loses the visual link to the acronym and class
> name
> > >
> > > If anyone has other proposals, please add them here and I'll include
> them
> > > when the vote opens Monday. Please see the collapsed section for more
> > > details and background.
> > >
> > > Best,
> > > Constance
> > >
> > > --
> > >
> > > Proposed framing for the vote:
> > >
> > > - Option A: Prefer dag in docs; use DAG only when referring to the
> > > class/import
> > > - Option B: Prefer Dag in docs; use DAG only for the class/import
> > > - Option C: Keep DAG as the standard everywhere (status quo)
> > >
> > > Option with the most votes wins. You can vote between -1 to +1 for any
> of
> > > the three options, and everyone will be encouraged to vote.
> > >
> > > Summary of viewpoints so far (AI- generated):
> > >
> > > - "dag" — clean, user-friendly, Pythonic, avoids shouting the
> acronym
> > > - "DAG" — consistent with current APIs and historical context
> > > - "Dag" — middle ground; distinguishes the concept from the acronym
> > > while keeping it recognizable
> > >
> > > Links:
> > >
> > > - https://lists.apache.org/thread/lktrzqkzrpvc1cyctxz7zxfmc0fwtq2j
> > > - https://lists.apache.org/thread/5fn1n188f99jspt627qhqsp2pznq545s
> > > - https://lists.apache.org/thread/q7zdogwb76jko3vwz7tlsnl2cn3h3vg9
> > >
> > > Constance
> > >
> >
>
Re: [DISCUSS] Finalizing “DAG” terminology for docs and blog ("dag" vs "DAG" vs "Dag")
Posted by Amogh Desai <am...@apache.org>.
Thanks for sending this notice, Constance.
The older thread just blew up with too many opinions and calling
a formal vote is the way to go.
Thanks & Regards,
Amogh Desai
On Thu, Oct 16, 2025 at 1:08 AM Jarek Potiuk <ja...@potiuk.com> wrote:
> Very nice summary ! Thanks Constance :)
>
> On Wed, Oct 15, 2025 at 9:27 PM Constance Martineau via dev <
> dev@airflow.apache.org> wrote:
>
> > Reviving this discussion after the canceled vote:
> > https://lists.apache.org/thread/q7zdogwb76jko3vwz7tlsnl2cn3h3vg9
> >
> > As mentioned earlier, I plan to *formally call a vote on Monday* to
> > finalize how we refer to Airflow workflows in writing (docs, tutorials,
> and
> > blog posts).
> >
> > This will *not* affect code (DAG and dag remain as-is in APIs and
> > decorators). The goal is to set a clear convention for prose so
> > contributors and vendors can align their content accordingly
> >
> > Why this matters: We’ve had inconsistent terminology across docs and
> > repeated PR debates over capitalization. Standardizing will make our
> > writing clearer, strengthen the Airflow brand, and give external
> > stakeholders a single reference to follow.
> >
> > Options for standardization:
> >
> >
> > 1. DAG (all caps)
> > - Matches existing imports (from airflow.sdk import DAG) and the
> > broader ecosystem.
> > - Keeps a nod to the original meaning ("directed acyclic graph")
> > which still fits conceptually even if we later allow more flexible
> > graph
> > types
> > - Counterpoint: Feels overly technical or academic for many readers
> > 2. Dag (capitalized)
> > - Treats it as an Airflow-specific concept ("a Dag" = an Airflow
> > workflow)
> > - Reads more naturally in writing than all caps.
> > - Counterpoint: Neither a class name nor a standard word form, so
> it
> > can feel inconsistent
> > 3. dag (lowercase)
> > - Reads like a common noun in Airflow vocabulary
> > - Matches Python identifiers (dag_id, dag.run_id) and blends
> cleanly
> > into text
> > - Counterpoint: Loses the visual link to the acronym and class name
> >
> > If anyone has other proposals, please add them here and I'll include them
> > when the vote opens Monday. Please see the collapsed section for more
> > details and background.
> >
> > Best,
> > Constance
> >
> > --
> >
> > Proposed framing for the vote:
> >
> > - Option A: Prefer dag in docs; use DAG only when referring to the
> > class/import
> > - Option B: Prefer Dag in docs; use DAG only for the class/import
> > - Option C: Keep DAG as the standard everywhere (status quo)
> >
> > Option with the most votes wins. You can vote between -1 to +1 for any of
> > the three options, and everyone will be encouraged to vote.
> >
> > Summary of viewpoints so far (AI- generated):
> >
> > - "dag" — clean, user-friendly, Pythonic, avoids shouting the acronym
> > - "DAG" — consistent with current APIs and historical context
> > - "Dag" — middle ground; distinguishes the concept from the acronym
> > while keeping it recognizable
> >
> > Links:
> >
> > - https://lists.apache.org/thread/lktrzqkzrpvc1cyctxz7zxfmc0fwtq2j
> > - https://lists.apache.org/thread/5fn1n188f99jspt627qhqsp2pznq545s
> > - https://lists.apache.org/thread/q7zdogwb76jko3vwz7tlsnl2cn3h3vg9
> >
> > Constance
> >
>
Re: [DISCUSS] Finalizing “DAG” terminology for docs and blog ("dag" vs "DAG" vs "Dag")
Posted by Jarek Potiuk <ja...@potiuk.com>.
Very nice summary ! Thanks Constance :)
On Wed, Oct 15, 2025 at 9:27 PM Constance Martineau via dev <
dev@airflow.apache.org> wrote:
> Reviving this discussion after the canceled vote:
> https://lists.apache.org/thread/q7zdogwb76jko3vwz7tlsnl2cn3h3vg9
>
> As mentioned earlier, I plan to *formally call a vote on Monday* to
> finalize how we refer to Airflow workflows in writing (docs, tutorials, and
> blog posts).
>
> This will *not* affect code (DAG and dag remain as-is in APIs and
> decorators). The goal is to set a clear convention for prose so
> contributors and vendors can align their content accordingly
>
> Why this matters: We’ve had inconsistent terminology across docs and
> repeated PR debates over capitalization. Standardizing will make our
> writing clearer, strengthen the Airflow brand, and give external
> stakeholders a single reference to follow.
>
> Options for standardization:
>
>
> 1. DAG (all caps)
> - Matches existing imports (from airflow.sdk import DAG) and the
> broader ecosystem.
> - Keeps a nod to the original meaning ("directed acyclic graph")
> which still fits conceptually even if we later allow more flexible
> graph
> types
> - Counterpoint: Feels overly technical or academic for many readers
> 2. Dag (capitalized)
> - Treats it as an Airflow-specific concept ("a Dag" = an Airflow
> workflow)
> - Reads more naturally in writing than all caps.
> - Counterpoint: Neither a class name nor a standard word form, so it
> can feel inconsistent
> 3. dag (lowercase)
> - Reads like a common noun in Airflow vocabulary
> - Matches Python identifiers (dag_id, dag.run_id) and blends cleanly
> into text
> - Counterpoint: Loses the visual link to the acronym and class name
>
> If anyone has other proposals, please add them here and I'll include them
> when the vote opens Monday. Please see the collapsed section for more
> details and background.
>
> Best,
> Constance
>
> --
>
> Proposed framing for the vote:
>
> - Option A: Prefer dag in docs; use DAG only when referring to the
> class/import
> - Option B: Prefer Dag in docs; use DAG only for the class/import
> - Option C: Keep DAG as the standard everywhere (status quo)
>
> Option with the most votes wins. You can vote between -1 to +1 for any of
> the three options, and everyone will be encouraged to vote.
>
> Summary of viewpoints so far (AI- generated):
>
> - "dag" — clean, user-friendly, Pythonic, avoids shouting the acronym
> - "DAG" — consistent with current APIs and historical context
> - "Dag" — middle ground; distinguishes the concept from the acronym
> while keeping it recognizable
>
> Links:
>
> - https://lists.apache.org/thread/lktrzqkzrpvc1cyctxz7zxfmc0fwtq2j
> - https://lists.apache.org/thread/5fn1n188f99jspt627qhqsp2pznq545s
> - https://lists.apache.org/thread/q7zdogwb76jko3vwz7tlsnl2cn3h3vg9
>
> Constance
>