Docs: align Dag spelling with Airflow community usage#2622
Conversation
Replace standalone DAG/DAGs with Dag/Dags across docs prose to match the Apache Airflow community's preferred spelling. Identifier-style references such as AIRFLOW__DAG_PROCESSOR__* and DAG_FOLDER are preserved. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
pankajkoti
requested review from
a team,
corsettigyg,
dwreeves and
jbandoro
as code owners
There was a problem hiding this comment.
Pull request overview
Updates documentation prose to align with the Airflow community’s preferred “Dag/Dags” spelling, while intending to preserve identifier-style references (env vars, constants, class names).
Changes:
- Sweep docs to replace prose “DAG/DAGs” with “Dag/Dags” across reference pages, guides, policies, and performance docs
- Update headings, bullet text, and narrative examples accordingly
- Keep identifier-style strings (e.g.,
AIRFLOW__DAG_PROCESSOR__*) as-is (intended)
Reviewed changes
Copilot reviewed 44 out of 44 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/reference/configs/project-config.rst | Prose update (“DAG parsing” → “Dag parsing”) in config reference |
| docs/reference/configs/execution-config.rst | Prose update (“DAGs” → “Dags”) in config reference |
| docs/reference/configs/cosmos-conf.rst | Prose update for versioning and parsing references |
| docs/policy/policies.rst | Prose update in repository/policy listing |
| docs/policy/contributing.rst | Prose update in local dev setup instructions |
| docs/policy/compatibility-policy.rst | Prose update in compatibility requirements list |
| docs/policy/airflow3-compatibility.rst | Prose updates in warning + validation bullets |
| docs/optimize_performance/troubleshooting.rst | Prose updates for parse-time troubleshooting terminology |
| docs/optimize_performance/optimize_rendering.rst | Prose updates in rendering optimization guidance |
| docs/optimize_performance/optimize_execution.rst | Prose updates in execution optimization guidance |
| docs/optimize_performance/memory_optimization.rst | Prose updates in concurrency/memory guidance |
| docs/optimize_performance/index.rst | Prose updates in section overview bullets |
| docs/optimize_performance/caching.rst | Prose updates in caching discussion and terminology |
| docs/index.rst | Prose update in docs landing page intro |
| docs/guides/translate_dbt_to_airflow/testing-behavior.rst | Prose updates in testing behavior guide |
| docs/guides/translate_dbt_to_airflow/selecting-excluding.rst | Prose updates around manifest filtering and parsing |
| docs/guides/translate_dbt_to_airflow/render-config.rst | Prose updates in RenderConfig reference text |
| docs/guides/translate_dbt_to_airflow/parsing-methods.rst | Prose updates in parsing methods guide |
| docs/guides/translate_dbt_to_airflow/managing-sources.rst | Prose updates for source rendering/pruning |
| docs/guides/translate_dbt_to_airflow/dag-customization.rst | Prose updates in post-render customization guide |
| docs/guides/run_dbt/operators/operator-args.rst | Prose updates in operator args reference |
| docs/guides/run_dbt/execution-modes.rst | Prose update in execution modes overview |
| docs/guides/run_dbt/customization/scheduling.rst | Prose updates; also includes code example edits |
| docs/guides/run_dbt/customization/partial-parsing.rst | Prose update referencing parsing speedups |
| docs/guides/run_dbt/container/watcher-kubernetes-execution-mode.rst | Prose updates in WATCHER_KUBERNETES guide |
| docs/guides/run_dbt/container/kubernetes.rst | Prose updates for Kubernetes guide |
| docs/guides/run_dbt/container/gcp-cloud-run-job.rst | Prose updates for Cloud Run guide |
| docs/guides/run_dbt/container/docker.rst | Prose updates for Docker guide |
| docs/guides/run_dbt/container/azure-container-instance.rst | Prose updates for Azure Container Instances guide |
| docs/guides/run_dbt/container/aws-eks.rst | Prose updates for AWS EKS guide |
| docs/guides/run_dbt/container/aws-container-run-job.rst | Prose updates for AWS ECS/container run guide |
| docs/guides/run_dbt/callbacks/callbacks.rst | Prose updates for callbacks guide |
| docs/guides/run_dbt/airflow-worker/watcher-execution-mode.rst | Prose updates; also includes code example edits |
| docs/guides/run_dbt/airflow-worker/async-execution-mode.rst | Prose updates in async mode guide |
| docs/guides/multi_project/multi-project.rst | Prose updates; also includes code example edits |
| docs/guides/dbt_docs/hosting-docs.rst | Prose update referencing the dags folder |
| docs/guides/dbt_docs/generating-docs.rst | Prose updates around example usage |
| docs/guides/cosmos_devex/lineage.rst | Prose update referencing user DAG files |
| docs/guides/cosmos_devex/compiled-sql.rst | Prose update referencing DAG/Task Group args |
| docs/getting_started/open-source.rst | Prose updates around “DAGs directory” wording |
| docs/getting_started/mwaa.rst | Prose updates around “DAGs directory” wording |
| docs/getting_started/gcc.rst | Prose updates around “DAGs directory” wording |
| docs/getting_started/dbt-airflow-concepts.rst | Prose updates in Airflow/dbt concepts table |
| docs/getting_started/astro.rst | Prose updates around getting-started instructions |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Airflow's DAG class is named DAG (uppercase). The earlier sweep incorrectly rewrote it to Dag inside Python imports and constructor calls, breaking copy-paste of the examples. Revert those identifiers while keeping Dag in surrounding prose.
tatiana
left a comment
tatiana
left a comment
There was a problem hiding this comment.
Thanks for picking up this consistency work! I do think we need a coherent standard across the docs.
That said, I have a concern about adopting Dag specifically. DAG is an acronym (Directed Acyclic Graph), so the all-caps form isn't just a stylistic choice — it's the grammatically correct treatment of an initialism. Lowercasing it to Dag suggests it's being treated as a regular word, which could read as a spelling error to users who know what it stands for.
I understand that parts of the Airflow community are moving in this direction, but I'd want to understand the rationale before we align to it. Is there an AIP or style guide decision we could reference? If the upstream reasoning is solid, I'm open to it - I'd just want us to make this change deliberately rather than implicitly inherit it.
As an alternative, I'd like to propose replacing occurrences of DAG with workflow or pipeline, and reserving DAG (and Dag when the class name is used) exclusively for code blocks where those identifiers are actually instantiated. This would make the docs more accessible to users unfamiliar with Airflow-specific terminology, while keeping technical references accurate.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 44 out of 44 changed files in this pull request and generated 2 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
The sample log lines in optimize_rendering.rst and troubleshooting.rst are meant to be grep-able against Cosmos's actual log output. The real log message in cosmos/converter.py is "for DAG using ...", so keep the capitalization as DAG in those code blocks even though the surrounding prose uses Dag.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 44 out of 44 changed files in this pull request and generated 11 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 44 out of 44 changed files in this pull request and generated 4 comments.
Comments suppressed due to low confidence (1)
docs/guides/run_dbt/container/aws-container-run-job.rst:206
- The closing reminder uses “config” as a verb (“Remember to config your Dag…”), while earlier in the same section it says “configure” (line 179). For consistency and correct grammar, change this to “configure”.
Happy deploying! :rocket:
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
I remember a vote was carried out previously to finalise this, and I see the majority of the people voted for I also see PRs created in the Airflow repo to conduct such changes: apache/airflow#55097 And this is a PR we are creating from the previous proposed PRs for style guides in Cosmos: #2460, #2462 |
- dbt-airflow-concepts.rst: fix the long-standing typo "Direct Acyclic Graph" to "Directed Acyclic Graph". - caching.rst: rephrase the awkward "reduced some Dags task queueing from 30s to 0s" to "reduced task queueing time for some Dags". - render-config.rst: change one residual "DAGs" in prose to "Dags" so the page is internally consistent with the surrounding "Dag" usage.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 44 out of 44 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 44 out of 44 changed files in this pull request and generated 3 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| Cosmos aims to give you control over how your dbt project is executed when running in airflow. | ||
| It does this by exposing a ``cosmos.config.ExecutionConfig`` class that you can use to configure how your DAGs are executed. | ||
| It does this by exposing a ``cosmos.config.ExecutionConfig`` class that you can use to configure how your Dags are executed. |
| - ``enable_mock_profile``: When using ``LoadMode.DBT_LS`` with a ``ProfileMapping`` class, by default, Cosmos mocks the values of the profile. Defaults to True. In order to leverage partial parsing, this argument should be set to ``False``. Read `Partial parsing <./partial-parsing.html#profile-configuration.html>`_ for more information. | ||
| - ``env_vars``: (available in v1.2.5, use``ProjectConfig.env_vars`` for v1.3.0 onwards) A dictionary of environment variables for rendering. Only supported when using ``load_method=LoadMode.DBT_LS``. | ||
| - ``dbt_project_path``: Configures the DBT project location accessible on their airflow controller for DAG rendering - Required when using ``load_method=LoadMode.DBT_LS`` or ``load_method=LoadMode.CUSTOM`` | ||
| - ``dbt_project_path``: Configures the DBT project location accessible on their airflow controller for Dag rendering - Required when using ``load_method=LoadMode.DBT_LS`` or ``load_method=LoadMode.CUSTOM`` | ||
| - ``airflow_vars_to_purge_dbt_ls_cache``: (new in v1.5) Specify Airflow variables that will affect the ``LoadMode.DBT_LS`` cache. See `Caching <./caching.html>`_ for more information. |
| - ``normalize_task_display_name``: This function allows users to set a custom user-defined function to alter the display name independently of the model name. This way, the task_id can be preserved while the model display name is modified. | ||
| - ``should_detach_multiple_parents_tests``: A boolean to control if tests that depend on multiple parents should be run as standalone tasks. See `Testing Behavior <testing-behavior.html>`_ for more information. | ||
| - ``enable_owner_inheritance``: (introduced in 1.10.2) A boolean to control if dbt owners should be imported as part of the airflow DAG owners. Defaults to True. | ||
| - ``enable_owner_inheritance``: (introduced in 1.10.2) A boolean to control if dbt owners should be imported as part of the airflow Dag owners. Defaults to True. |
| └── ... | ||
|
|
||
| Note: dbt projects can be placed anywhere in the Airflow image or mounted independently via the `astro dbt deploy <https://www.astronomer.io/docs/astro/cli/astro-dbt-deploy>`__ command. You can customise where the dbt project is by setting the ``dbt_project_path`` parameter on ``ProjectConfig`` when you create your DAG instance. | ||
| Note: dbt projects can be placed anywhere in the Airflow image or mounted independently via the `astro dbt deploy <https://www.astronomer.io/docs/astro/cli/astro-dbt-deploy>`__ command. You can customise where the dbt project is by setting the ``dbt_project_path`` parameter on ``ProjectConfig`` when you create your Dag instance. |
There was a problem hiding this comment.
| Note: dbt projects can be placed anywhere in the Airflow image or mounted independently via the `astro dbt deploy <https://www.astronomer.io/docs/astro/cli/astro-dbt-deploy>`__ command. You can customise where the dbt project is by setting the ``dbt_project_path`` parameter on ``ProjectConfig`` when you create your Dag instance. | |
| Note: dbt projects can be placed anywhere in the Airflow image or mounted independently via the `astro dbt deploy <https://www.astronomer.io/docs/astro/cli/astro-dbt-deploy>`__ command. You can customise where the dbt project is by setting the ``dbt_project_path`` parameter on ``ProjectConfig`` when you create your `DAG` instance. |
|
Based on discussions with @tatiana and @pankajastro, we’ve agreed to hold off on merging this PR for now and defer these changes to a later time. |
Description
Per the lightweight style guide proposed in #2460, sweep the docs prose to use
Dag/Dagsinstead ofDAG/DAGs, matching the Apache Airflow community'spreferred spelling. Identifier-style references like
AIRFLOW__DAG_PROCESSOR__*,DAG_FOLDER, and Python class names (e.g.DbtDag) are preserved.This re-applies the
DAG → Dagportion of #2462 against currentmainas afocused, standalone change.
Related Issue(s)
Refs #2460
Breaking Change?
No. Documentation only.
Checklist