企业官网建设流程全解析

Apache Airflow 贡献工作流全指南：从 Fork 到 PR 合并的完整实战流程

【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow

Apache Airflow 是一个以编程方式编写、调度和监控工作流的平台，其社区贡献规模庞大。本文以仓库中的 贡献工作流文档 为骨架，完整讲解一次贡献从「挑选 Issue → 搭建开发环境 → 编写代码 → 提交 PR → 通过评审 → 被合并」的全过程。读完本文，你将掌握 Airflow 的 Git 分支与远程仓库约定、本地 virtualenv 与 Breeze 两种开发环境的搭建方法、newsfragment 的写作规范、PR 质量门槛与评审规则，并能结合仓库源码理解每一步背后的实现逻辑。

贡献流程总览：一次 PR 的生命周期

通常，你的第一次贡献始于浏览 Apache Airflow 的 GitHub Issues 中的待办工单。创建 PR 不强制要求先建 Issue，但如果你愿意，可以先建一个 Issue——这能让你提前收集反馈或与其他人分享计划。

例如，你可以认领一个类似「#7782: Add extra CC: to the emails sent by Airflow」的工单——该工单要求为 Airflow 发送的邮件增加额外的 CC 收件人支持。

一般而言，一次完整的贡献包含以下阶段：

1. Fork：在 GitHub 上创建 Apache Airflow 主仓库的个人副本（fork）。
2. 准备环境：创建本地 virtualenv，初始化 Breeze 开发环境，安装 prek 钩子工具。如果计划长期持续贡献，还需配置好 fork 并启用 GitHub Actions。
3. 融入社区：加入开发者邮件列表并注册 Slack 账号。
4. 提交 PR：完成代码修改，从你的 fork 创建 Pull Request。
5. 推进评审：在 #contributors Slack 频道 ping 一下、@ 相关人员，保持礼貌地跟进——既要有耐心，也要积极。

这一流程对应的示意图保存在 contributing-docs/images/workflow.png，下面我们按步骤逐一展开。

Apache Airflow 贡献工作流总览图

Step 1：Fork Apache Airflow 仓库

在 apache/airflow 仓库页面上点击「Fork」按钮创建你自己的副本（GitHub 官方 Fork 指南）。Fork 完成后，你的个人账号下会出现一个独立的airflow仓库副本，所有 PR 分支都应推送到这里，而不是直接推送到上游。

在 GitHub 上创建 fork

Step 2：配置你的开发环境

Airflow 支持多种开发环境：本地机器上可以选择Local Virtualenv或 Docker 化的Breeze 环境，此外还支持 GitHub Codespaces 和 GitPodify 等远程开发环境。各环境的详细对比见 Development environments。

三种环境怎么选

从仓库中的 环境对比文档 可以看到三种环境的核心差异：

建议：根据需求组合使用多种环境。日常开发和调试用 local virtualenv（IDE 集成最顺畅），需要运行依赖 MySQL、Hadoop、Mongo、Cassandra、Redis 等外部组件的集成测试时，用 Breeze（它提供了与 CI 几乎一致的 Docker Compose 环境）。

搭建 Breeze（Docker 化开发环境）

Breeze 的目标是维护一个一致、通用的开发环境，让你能在本地复现 CI 失败并解决它，而不是反复推送到 CI 去试错。搭建步骤如下：

1. 安装最新版 Docker Community Edition 与 Docker Compose，并加入PATH。
2. 安装jq。例如 Ubuntu 上：

   sudo apt install jq

   或 macOS 上用 Homebrew：

   brew install jq

3. 在 Airflow 源码目录中直接运行：

   breeze

   Breeze 会从 Docker Hub 下载 Airflow CI 镜像并安装所有依赖，随后进入 Docker 环境，并将你的本地源码挂载进容器——修改立即在环境中可见。

从源码看，Breeze 的完整实现位于 dev/breeze 目录，其入口和说明文档见 dev/breeze/doc/README.rst。值得注意的一点：Breeze 的 CI 镜像不应用于生产环境，它优化的是测试可复现性、可维护性和构建速度，生产环境应使用 DockerHub 发布的 PROD 镜像。

搭建本地 virtualenv

创建本地虚拟环境并初始化：

python3 -m venv venv && source venv/bin/activate ./scripts/tools/initialize_virtualenv.py

随后打开你的 IDE（如 PyCharm），把刚创建的虚拟环境设为项目的默认解释器，即可获得自动补全和 IDE 内直接运行测试的能力。

关于本地环境的更多细节（系统依赖清单、uv 用法、连接数据库调试等）见 Local virtualenv 文档。该文档指出，自 2024 年 11 月起项目推荐使用uv管理本地虚拟环境：在仓库根目录运行uv sync即可依据 pyproject.toml 与已提交的 uv.lock 一次性同步 Airflow 核心、所有 providers 及其开发依赖；只想改某个 provider 时，在该 provider 目录下运行uv sync再用uv run pytest跑测试即可。

Step 3：与社区建立联系

为了高效协作，建议加入以下 Airflow 沟通渠道：

• 邮件列表（订阅即向对应地址发送一封空邮件）：
  • 开发者邮件列表：<dev-subscribe@airflow.apache.org>（流量较大）
  • 全部提交邮件列表：<commits-subscribe@airflow.apache.org>（流量非常大）
  • 用户邮件列表：<users-subscribe@airflow.apache.org>（流量适中）
• GitHub Issues：跟踪 bug 与功能请求
• Slack（即时聊天）：日常交流与求助

Step 4：准备你的 PR

4.1 围绕示例 Issue 完成代码修改

以「为邮件增加 CC 收件人」这个示例工单为例，完整路径如下：

1. 阅读相关文档：先读 邮件配置文档，理解 Airflow 邮件发送的配置方式。

2. 定位要修改的类：该示例需要修改的是 email.py（核心邮件发送工具模块）。

3. 定位要补测试的文件：对应的测试类是 test_email.py。

4. 同步 fork：创建分支前，务必确保你 fork 的main与 Apache Airflow 的main同步（详见下文「同步 fork」与「Git 远程命名约定」）。

5. 创建本地分支：以最新的upstream/main为基底创建开发分支。Airflow 社区标准化约定两个远程名：upstream→apache/airflow（拉取），origin→ 你的 fork（推送 PR 分支）。虽然直接在 fork 的main上开发也可以，但强烈建议为每次开发创建独立分支，便于对比改动、并行处理多个任务。

   配置好upstream后，在本地main分支上执行git pull upstream main即可获得最新变更；若本地main有冲突想直接覆盖，可执行：

   git fetch upstream; git reset --hard upstream/main

6. 修改代码并补充单元测试：修改类、添加必要代码与单元测试。

7. 运行并修复所有静态检查：若已安装 prek 钩子，提交时代码会自动执行检查；否则手动git add后运行prek。

8. 运行相应测试：按 Testing 文档 的说明运行适当的测试。

9. 考虑添加 newsfragment（详见 4.3 节）。

关于 rebase 的具体操作（git merge-base、git rebase HASH --onto upstream/main、git push --force-with-lease等），可参考 Working with Git 文档。

4.2 Git 远程命名约定与分支模型

仓库中的 Working with Git 文档对远程命名与分支策略有明确规定：

• upstream= 规范的apache/airflow仓库（从中 fetch）
• origin= 你的 fork（向其 push PR 分支）
• 所有新开发都发生在main分支（当前为 Airflow 3），所有 PR 都应指向main；另有v2-10-test等维护分支用于 cherry-pick 修复。

如果现有 checkout 的远程名不符合约定，可执行迁移：

# 情形 1：upstream 当前叫 "apache" git remote rename apache upstream # 情形 2：origin 指向 apache/airflow，你的 fork 叫 "fork" git remote rename origin upstream git remote rename fork origin # 情形 3：缺少 upstream git remote add upstream https://github.com/apache/airflow.git

仓库还提供了 dev/sync_fork.sh 辅助脚本，可一次同步main与当前发布分支到 fork（脚本使用git push --force，会覆盖 fork 上列出的分支，请先确认没有未提交的工作）：

# 同步默认分支（main 与当前发布分支） ./dev/sync_fork.sh # 只同步 main ./dev/sync_fork.sh main # 同步指定分支集合 ./dev/sync_fork.sh main v3-2-test v3-1-test

4.3 添加 newsfragment（版本发布说明条目）

为了让改动进入 release notes，建议在 PR 中附带一个 newsfragment。支持的 newsfragment 类型有：

• significant（重要变化，不一定必须是破坏性变更，但值得在发布说明中特别指出）
• feature（新功能）
• improvement（改进）
• bugfix（缺陷修复）
• doc（仅文档变更）
• misc（杂项）

命名规则为{pr_number}.{type}.rst，例如1234.bugfix.rst。放置位置：

• Airflow 核心的 newsfragment 放入 airflow-core/newsfragments 目录（该目录下已有大量真实示例，如70013.feature.rst、72042.bugfix.rst）；
• Helm Chart 的 newsfragment 放入 chart/newsfragments 目录。

内容规范：普通类型的 newsfragment必须只有一行；significant类型可以包含摘要与正文，两者之间用空行分隔（类似 git commit message 的写法）。

这些规则并非口头约定，仓库有真实的 CI 校验脚本 scripts/ci/prek/newsfragments.py 强制执行。从源码看，其validate_newsfragment函数会校验：

• 文件名必须恰好是{pr_number}.{type}.rst三段式结构；
• 类型必须属于上面六种之一；
• 非significant类型只能有一行内容；
• significant类型允许 1 行或 3 行以上（且第 2 行必须为空），2 行会被拒绝。

此外，[airflow-core/newsfragments/config.toml](https://link.gitcode.com/i/b3beff901c8d3b288149fc8a6bf5d582)是 towncrier 工具的配置，定义了各类型对应的发布说明章节名（如 significant → "Significant Changes"、feature → "Features" 等），发布时 towncrier 会依据它把 newsfragment 聚合进 airflow-core/RELEASE_NOTES.rst（注意config.toml中filename = "../RELEASE_NOTES.rst"指向的核心 release notes 文件）。

由于 CI 会校验 newsfragment 文件名必须使用正确的 PR 号，如果你需要跳过该校验（例如从另一个 PR cherry-pick newsfragment 时），可以给 PR 打上skip newsfragment check标签。

4.4 提交前的收尾工作

1. Rebase fork、squash 提交并解决所有冲突：参见 How to rebase PR。如果 PR 耗时较长，记得经常 rebase——越频繁，冲突越少，越轻松。解决uv.lock冲突的推荐方式是删除该文件后重新运行uv lock重新生成。
2. 重新运行静态代码检查。
3. 写好提交信息：提交标题和描述要足以让维护者理解你为何提出这个改动，遵循 Pull Request guidelines。
4. 创建 Pull Request，准备好迎接讨论。

4.5 关于评审时机的现实规则

• 静态检查和测试是质量第一道门槛：在 PR 变「绿」之前，维护者通常不会评审（除非你特别请求首轮反馈并说明为何难以/不适合/不期望达成绿状态）。
• [WIP]或 Draft 状态的 PR 不会被评审：除非你明确说明原因和希望得到哪方面反馈（例如想先确认 PR 方向或设计）。
• 避免 @ 单个维护者：除非有充分理由相信对方有空且感兴趣。Airflow 没有「专属」评审人，维护者都是在自己有空时评审。如果几天没有反应，可以礼貌地跟进（这会把你 PR 顶到「最近评论」列表顶部），但要注意时区、假期和忙碌期——一般来说，作者有责任在希望 PR 被评审和合并时跟进它。

Step 5：通过 PR 评审

5.1 评审交互规则

注意：维护者合并 PR 时使用Squash and Merge（而非 Rebase and Merge），你的所有提交会被压缩为单个提交。评审过程中你可以保留完整提交历史以便评审，也可以在 rebase 时 squash 以减少维护负担。

当评审者发起对话时，期望你回应问题、建议和疑问，让所有对话趋于共识。你不必采纳所有建议（即使建议来自资深维护者，那也常常只是观点），完全可以阐述自己的理解与方案——只要论据充分。评审者的回复通常有几类：

• General PR comment（整体评论）：通常是关于如何改进 PR 的问题/观点/建议，或要求你解释对 PR 的理解。这类评论有时会引发出多轮讨论，甚至被要求把讨论移到 devlist，或衍生出全新的 PR。
• 针对特定代码行的评论/对话：通常标记潜在的改进点或潜在问题。作为作者，你可以解决（resolve）对话（如果你认为问题已解决），也可以请评审者重新评审或确认；看不懂就请求澄清。请假设评审者是善意的——被批评的是代码本身，而不是人。
• Request changes（请求变更）：维护者比较确信你的 PR 存在严重缺陷、设计误解、bug 或不符合社区通行做法。通常你应该修复问题或说服维护者他们是错的（这种情况比你想的更常见）。若无法达成共识且你认为问题重要，可以在 devlist 发起讨论并投票。Request changes状态若不被撤回，该 PR 无法合并——根据 Apache Software Foundation 规则，维护者有权否决任何代码修改。
• Approval（批准）：评审完成后维护者认为可以合并。此时可能仍有未解决的对话，你需要在合并前解决它们。Approval是维护者信任的标志：只要评论被解决，就不必再逐条复核验证。

5.2 可合并的标准

PR 必须满足以下条件才能被合并：

• 静态检查与测试为绿（green status）
• 所有对话均已解决（conversations resolved）
• 至少 1 位维护者批准（若你是维护者本人，则必须由另一位维护者批准）；涉及 Airflow 核心代码时理想情况下应有 2 位或更多维护者评审（虽无强制要求，但维护者会视情况主动请求二次评审）
• 没有未解决的Request changes

一旦满足以上条件，你无需再做任何事，会有维护者来合并。但若几天过去仍未被合并，可以评论说明你认为它已准备好被合并。同时，建议把 PR rebase 到最新main——期间可能有其他变更导致冲突或测试失败，rebase 能确保它今天依然通过测试与静态检查。

PR 评审过程示意图

附：PR 质量门槛与社区规范速览

虽然主流程已经走完，但仓库的 Pull Request 文档 还定义了几条维护者评审前的最低质量门槛，了解它们能避免 PR 被自动转为 Draft：

1. 描述性标题：必须清楚描述改动，泛化标题（"Fix bug"、"Update code"）或只引用 issue 号（"Fixes #12345"）不达标。
2. 祈使语气标题（黄金法则）：始终使用祈使语气，不要用过去时，也不要用 conventional commits 前缀——例如用 "Add new feature" 而非 "feat: add new feature" 或 "Added this new feature"。
3. 有意义的描述：PR 正文必须说明改了什么、为什么，空正文或只重复标题不算。
4. 静态检查通过：可本地用prek run --from-ref main验证（ruff / mypy）。
5. Gen-AI 辅助披露：若 PR 借助生成式 AI 工具创建，描述中必须声明，且作者需对生成代码负最终责任——盲目复制粘贴 AI 代码可能引入安全与稳定性风险，维护者有权关闭相关 PR。
6. 改动聚焦：只包含相关改动，不要把无关变更捆绑在一起。

此外，项目强制要求合并前解决所有对话，并约定若干编码规范（详见 05_pull_requests.rst）：生产代码不用assert（类型检查的TYPE_CHECKING场景除外）、数据库 session 遵循「显式优于隐式」且由调用方管理提交、时长计算用time.monotonic()/time.perf_counter()、Operator 的模板字段验证放在execute而非构造函数、不直接抛AirflowException（优先标准异常与 airflow-core/src/airflow/exceptions.py 中的具体异常类）等。

总结

一次成功的 Airflow 贡献，本质上是「遵循分支约定 + 使用标准化开发环境 + 满足自动化质量门槛 + 与评审者良性互动」的组合。核心要点可归纳为：所有 PR 指向main、远程命名遵循upstream/origin；开发环境优先 local virtualenv（配 prek 钩子）或 Breeze；提交时带上格式正确的 newsfragment；PR 变绿、对话解决、获得至少一位维护者批准后即可被 Squash and Merge。如果你想继续深入了解，可以依次阅读 静态代码检查（prek 钩子的安装与常用命令）、测试文档 和 Git 工作流详解。

【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow