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
