Very nice summary ! Thanks Constance :) On Wed, Oct 15, 2025 at 9:27 PM Constance Martineau via dev < [email protected]> 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 >
