This is an automated email from the ASF dual-hosted git repository.
Lee-W pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/main by this push:
new 2a89e90b9ea docs(agents): document Dag naming convention (#66393)
2a89e90b9ea is described below
commit 2a89e90b9eaf1bd8638731799ca47377aea3ccc9
Author: Wei Lee <[email protected]>
AuthorDate: Tue May 5 17:35:50 2026 +0800
docs(agents): document Dag naming convention (#66393)
---
.github/skills/airflow-translations/locales/th.md | 26 +++++++++++------------
AGENTS.md | 15 +++++++++++++
providers/AGENTS.md | 6 +++---
3 files changed, 31 insertions(+), 16 deletions(-)
diff --git a/.github/skills/airflow-translations/locales/th.md
b/.github/skills/airflow-translations/locales/th.md
index b67e4d01d61..9cd5658648e 100644
--- a/.github/skills/airflow-translations/locales/th.md
+++ b/.github/skills/airflow-translations/locales/th.md
@@ -13,8 +13,8 @@ The following technical terms should **remain in English** in
Thai translations:
### Core Technical Terms (คำศัพท์ทางเทคนิค)
-- **DAG** (Directed Acyclic Graph) - Keep as "DAG"
-- **DAG Run** - Keep as "DAG Run"
+- **Dag** - Keep as "Dag" (Airflow convention; never write "DAG")
+- **Dag Run** - Keep as "Dag Run"
- **Task Instance** - Keep as "Task Instance"
- **XCom** - Keep as "XCom"
- **Asset** - Keep as "Asset"
@@ -24,7 +24,7 @@ The following technical terms should **remain in English** in
Thai translations:
- **Sensor** - Keep as "Sensor"
- **Hook** - Keep as "Hook"
- **Operator** - Keep as "Operator" (โอเปอเรเตอร์) or in English
-- **DAGBag** - Keep as "DAGBag"
+- **DagBag** - Keep as "DagBag"
### UI Components (ส่วนประกอบของอินเทอร์เฟซ)
@@ -123,14 +123,14 @@ In Airflow UI and messages, numerals are typically
formatted as:
Example:
```text
-งาน DAG รันสำเร็จ (DAG run successful)
+งาน Dag รันสำเร็จ (Dag run successful)
```
## Translation Style Guidelines
### 1. Technical Terminology
-Keep technical terms like DAG, XCom, Operator in English when:
+Keep technical terms like Dag, XCom, Operator in English when:
- They appear in code or configuration examples
- No clear Thai equivalent exists
@@ -181,8 +181,8 @@ Prefer translation for:
### 1. "Run" Context
-- "Run DAG" → "รัน DAG" or "ดำเนินการ DAG"
-- "DAG run" (noun) → "การรัน DAG" or "DAG Run"
+- "Run Dag" → "รัน Dag" or "ดำเนินการ Dag"
+- "Dag run" (noun) → "การรัน Dag" or "Dag Run"
- "Run ID" → "รันไอดี" or "Run ID"
### 2. "Task" Context
@@ -191,11 +191,11 @@ Prefer translation for:
- "Task instance" → "Task Instance" or "อินสแตนซ์งาน"
- "Task ID" → "Task ID" or "ไอดีงาน"
-### 3. "DAG" Context
+### 3. "Dag" Context
-- "DAG run" → "การรัน DAG" or "DAG Run"
-- "DAG ID" → "DAG ID" or "ไอดี DAG"
-- "Sub DAG" → "DAG ย่อย" or "Sub DAG"
+- "Dag run" → "การรัน Dag" or "Dag Run"
+- "Dag ID" → "Dag ID" or "ไอดี Dag"
+- "Sub Dag" → "Dag ย่อย" or "Sub Dag"
### 4. Configuration
@@ -252,14 +252,14 @@ However, these are typically omitted in technical
documentation to maintain conc
"Tree View" → "มุมมองต้นไม้" or "Tree View"
"Graph View" → "มุมมองกราฟ" or "Graph View"
"Task Instances" → "Task Instances" or "อินสแตนซ์งาน"
-"DAG Runs" → "DAG Runs" or "การรัน DAG"
+"Dag Runs" → "Dag Runs" or "การรัน Dag"
```
### Message Examples
```text
"Task failed" → "งานล้มเหลว"
-"DAG run successful" → "การรัน DAG สำเร็จ"
+"Dag run successful" → "การรัน Dag สำเร็จ"
"XCom pushed" → "ดัน XCom แล้ว" or "XCom pushed"
"Connection test failed" → "การทดสอบการเชื่อมต่อล้มเหลว"
```
diff --git a/AGENTS.md b/AGENTS.md
index 8aeb5e0c601..1fc6aed1151 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -3,6 +3,21 @@
# AGENTS instructions
+## Naming
+
+Write **Dag** (title case) in all prose. Keep the all-caps or lowercase
+spelling only when reproducing a literal code token — never rewrite these,
+even inside fenced code blocks:
+
+- Python: the SDK class `DAG` (`from airflow.sdk import DAG`,
+ `dag = DAG("my_dag", ...)`); identifiers like `dag_id`, `dag`, `my_dag`.
+- CLI: `airflow dags list`, `airflow dags test`, etc.
+- Paths and config keys: `dag_processing/`, `dagprocessor`, `get_dag`, etc.
+- Anti-pattern quotes that show the wrong form to teach the rule itself
+ (e.g., `Use "DAG" — always write "Dag"`).
+
+Don't spell out **Directed Acyclic Graph** except for historical context.
+
## Environment Setup
- Install prek: `uv tool install prek`
diff --git a/providers/AGENTS.md b/providers/AGENTS.md
index bf75c002d4e..2e0e3d90f95 100644
--- a/providers/AGENTS.md
+++ b/providers/AGENTS.md
@@ -46,14 +46,14 @@ Airflow has two distinct user roles with different trust
levels:
- **Connection editors** — UI/API users with permission to create or edit
Connections. They control the host, login, password, and the `extra` JSON
blob.
-- **DAG authors** — users who write the Python code that constructs hooks
+- **Dag authors** — users who write the Python code that constructs hooks
and operators. They control which arguments are passed at call sites.
These are *not* the same population, and the security model treats them
differently. A Connection editor is trusted to supply credentials for a target
system; they are **not** trusted to alter how the worker process behaves, load
arbitrary Python code, change file paths the worker reads, or pass options
-into client libraries that the DAG author did not opt into.
+into client libraries that the Dag author did not opt into.
### What goes wrong when extras are forwarded blindly
@@ -90,7 +90,7 @@ model does not grant them.
- When adding support for a new extra key, treat it like any other public
argument: review what the underlying library does with it, and document
it in the provider's connection docs.
-- If a DAG author genuinely needs to pass a non-allowlisted option, that
+- If a Dag author genuinely needs to pass a non-allowlisted option, that
option should be a **Dag-author-supplied argument** on the operator or
hook (with its own review), not something a Connection editor can set.
