Traefik Pull Request 贡献全流程指南：从 PR 提交规范到 Lobicornis 合并机器人工作流

本文以 Traefik 仓库中的 Pull Request 贡献指南 为主体，系统讲解 Traefik Proxy 项目的 PR 优先级机制、提交前必须完成的本地验证命令、Triage 到 Merge 的评审周期，以及 Lobicornis 合并机器人的标签工作流。读完后，你可以按照项目维护者的实际要求完成一次可被快速评审、自动合并的规范 PR，并理解每一个 CI 检查与合入条件背后的仓库实现。

提交 PR 之前：如何选题与排定优先级

这篇指南面向已经准备好提交 pull request 的贡献者。如果你还需要搭建开发环境、学习如何写贡献代码，应先看 开发指南；如果你想找切入点，可以关注项目 Issue 列表中带 contributor/wanted（Priority Issues）、contributor/good-first-issue（Good First Issue）标签的条目，以及带 kind/bug/confirmed 标签的已确认缺陷——这三类是目前社区最欢迎的贡献方向。

Traefik 团队明确说明，受限于评审时间，无法即时处理所有 PR。从优先级上看：

处理速度最快的是：

• 文档更新（Documentation updates）；
• 缺陷修复（Bug fixes）；
• 带有 contributor/wanted 标签的增强与功能。

耗时较长的是：

• 未带 contributor/wanted 标签的增强或功能类 PR。

因此官方给出的核心建议是：先开 Issue，再写 PR。如果你有一个想实现的增强或功能，先在项目的 Issue 表单中创建 Issue 并表明你愿意为此写 PR；如果 Issue 已经存在，也务必评论表明参与意向。这样做有两个直接好处：

1. 团队可以与你直接沟通，提前确认这个方向是否会被接受，避免做完再被拒绝；
2. 在 Design 阶段就能获得团队的设计输入，使后续评审和合并更快速。

更细粒度的分诊规则记录在 Traefik 独立的 contributors-guide 仓库中的 Issue Triage 文档里，本文后续章节会给出其在 PR 流程中的具体作用。

PR 合并的硬性条件

一个 PR 要被自动合并，必须同时满足以下四组条件。第一组是"符合项目最佳实践"，这也是贡献指南中最细的一项清单：

最佳实践要求	说明
遵循项目约定	包括 维护者指南中的约定，且必须使用 PR 模板
保持 PR 小粒度	不要做大杂烩式 PR
一次只解决一个问题	多个问题拆成多个 PR
充分注释	解释每一处变更的意图与策略
不要从组织仓库（organization repository）发起 PR	仓库中有自动化机制直接关闭此类 PR
保持 "allows edit from maintainer" 勾选	便于维护者直接修改
文档类改动使用语义化换行（semantic line breaks）	每行独立成义，便于 diff 审查
确保 PR 不是 Draft	团队不评审 Draft，但会回答问题、与开发者讨论
go.mod 依赖必须引用 tag	若确实无法引用 tag，必须在 PR 中加注释说明原因

其余三组硬性条件是：通过 validation check、通过全部测试、获得 2 位维护者的 Approving Review。

PR 模板与目标分支

仓库内置的 PR 模板 本身就规定了目标分支的选择规则，这是提交前必须对齐的第一步：

PR 类型	目标分支
文档（Traefik v2）	v2.11（仅修复）
文档（Traefik v3.6 / v3.7）	对应的 v3.6 / v3.7 分支
Bug 修复（Traefik v2）	v2.11（仅安全修复）
Bug 修复（v3.6 / v3.7）	对应的 v3.6 / v3.7 分支
增强与功能	master

模板正文要求填写四个部分：What does this PR do?（变更描述）、Motivation（动机）、More（"Added/updated tests" 与 "Added/updated documentation" 两个勾选框）、Additional Notes（评审时需要了解的补充信息）。注意其中"Added/updated tests"勾选项对应后文"测试不充分或缺失会导致 PR 被降权"的评审规则。

"不从组织仓库发起 PR"是如何被自动执行的

指南中"Do not open the PR from an organization repository"这条规则在仓库里有对应的强制工作流：close-org-fork-pr.yaml。该 workflow 监听 pull_request_target 的 opened 事件，当 head.repo.fork == true 且 fork 的 owner 类型为 Organization 时，自动用 gh pr comment 留下解释评论并 gh pr close。其给出的原因是：团队依赖自动化机器人（即后文的 Lobicornis）完成 rebase 与 merge，而 GitHub 的权限模型不支持对组织 fork 发起的 PR 执行这套流程，因此要求贡献者改用个人 fork 重新发起。这一证据说明"最佳实践清单"并非仅靠人工检查，而是部分由 CI 直接强制。

评审周期：Triage、Design Review、Code Review 到 Merge

参照 Traefik 的 Triage Process，一个 PR 进入评审后的完整周期如下：

1. Triage（分诊）：每个新 PR 或新评论都会先经过分诊，再进入评审流程。分诊时确认所有评审前置条件已满足、确认使用场景符合项目需要，并指派评审人。
2. Design Review（设计评审）：这是周期中最长的环节，重点检查 PR 与现有代码库之间是否存在明显冲突。
3. Code Review（代码评审）：深入评审代码并运行测试，可能要求修改。指南明确要求贡献者在此阶段"合理地保持响应（reasonably responsive）"——如果 PR 在代码评审中长时间停滞，将面临被拒绝的风险，或者维护者会接手该 PR、原贡献者转为 co-author。此外，维护者可以添加 ai/review 标签触发自动化 AI 评审（详见后文"AI 辅助代码评审"一节）。
4. Merge（合并）：全部条件满足后由机器人自动合并。

需要额外留意的一点：团队偶尔会为了推进某个可能影响其他开发的功能或目标而冻结代码库。冻结期间你的 PR 可能处于未合并状态直到发布工作完成，这属于正常现象而非评审停滞。

提交前必须本地运行的验证命令

指南明确要求：在提交 PR 前必须本地跑完以下验证，以预测 CI 的通过与否——这些检查在 CI 上变绿之前，PR 不会被评审。结合仓库根目录 Makefile 的实际定义，这六个目标各自的含义与实现如下：

命令	Makefile 实现	作用
make generate	执行 go generate	生成动态/静态配置的文档引用文件
make generate-crd	执行 script/code-gen.sh	生成 Kubernetes CRD clientset 与 CRD manifests
make test-gateway-api-conformance	先 build-image-dirty，再以 -tags gatewayAPIConformance 运行 GatewayAPIConformanceSuite	运行 Gateway API 一致性测试
make validate	lint（golangci-lint）+ validate-files	校验代码、文档与 vendor 目录
make pull-images	从 ./integration/resources/compose/*.yml 提取 image: 字段并行拉取	避免集成测试期间拉镜像超时
make test	test-ui-unit + test-unit + test-integration	运行单元与集成测试

几个值得展开的细节：

make generate 的生成入口。 仓库根目录的 generate.go 只有一行指令 //go:generate go run ./internal/，即调用 internal/gendoc.go 所在包从 Go 配置结构体生成 docs/content/reference/static-configuration 与 docs/content/reference/dynamic-configuration 下的文档引用文件。凡是修改了 pkg/config/static 或 pkg/config/dynamic 中任何配置字段的 PR，都必须重新执行 make generate，否则文档引用与代码会不一致，文档校验会失败。

make generate-crd 的三段式生成。 script/code-gen.sh 固定了代码生成器版本：k8s.io/code-generator@v0.35.2（deepcopy-gen）与 sigs.k8s.io/controller-tools@v0.19.0（controller-gen）。它依次完成三件事：

1. 用 kube::codegen::gen_client 在 pkg/provider/kubernetes/crd/generated 下生成 clientset、applyconfig 与 watch 代码，头部注释取自 script/boilerplate.go.tmpl；
2. 用 controller-gen 从 pkg/provider/kubernetes/crd/traefikio/v1alpha1 包生成 v1 版 CRD 定义，输出到 docs/content/reference/dynamic-configuration/；
3. 将所有 traefik.io_*.yaml 拼接为 kubernetes-crd-definition-v1.yml，并同步复制到 integration/fixtures/k8s/01-traefik-crd.yml 供集成测试使用。

这意味着修改任何 Traefik CRD 类型的 PR，必须同时让文档参考与集成测试 fixture 两份产物保持一致——这正是"提交前本地跑 generate-crd"的原因。

make validate 的校验范围。 在 Makefile 中，validate 由 lint 与 validate-files 组成：前者执行 golangci-lint run；后者要求 misspell 与 shellcheck 必须在 PATH 中（缺失会直接报错），然后依次执行 script/validate-vendor.sh（校验 vendor 目录）、script/validate-misspell.sh（拼写检查）与 script/validate-shell-script.sh（shell 脚本检查）。文档侧另有独立的 docs/Makefile，通过 docs-lint 与 docs-verify 目标以容器方式运行 docs/scripts/lint.sh 与 docs/scripts/verify.sh 校验文档站，对应 .github/workflows/documentation.yaml 与 check_doc.yaml 两个 CI。

make test 的三级测试。 test-unit 对 ./pkg/... 与 ./cmd/... 全量跑 go test -cover；test-integration 只跑 ./integration 包，超时设为 20 分钟且 -failfast；test-ui-unit 会先构建 webui 的 Docker 镜像（webui/buildx.Dockerfile）再在容器内执行 yarn test:unit:ci。集成测试依赖大量外部容器镜像，因此指南把 make pull-images 单独列在 make test 之前，用于预热镜像缓存。

对应到 CI 侧，仓库的 .github/workflows/ 目录下有与上述目标一一对应的流水线：validate.yaml、test-unit.yaml、test-integration.yaml、test-gateway-api-conformance.yaml 以及 documentation.yaml。本地跑绿的检查项与 CI 中的 job 是同一套，这正是"本地先验证"策略的依据。

测试与合并工作流：Lobicornis 机器人

PR 的合并由 Traefik 的维护机器人 Lobicornis 统一管理。它负责核验 GitHub Checks（CI、测试等）、可合并性（mergability）与最低评审数，并在需要时执行 rebase 或 merge 到基础分支，此外还承担若干日常维护任务。对贡献者而言，需要掌握的是围绕它的标签协议：

标签	谁使用	语义
status/3-needs-merge	给出最终 LGTM 的维护者	触发合并机器人执行合并
status/4-merge-in-progress	仅机器人	表示合并正在进行中
bot/need-human-merge	机器人	机器人无法完成合并时添加；贡献者应解决冲突/CI 问题后移除该标签
bot/no-merge	贡献者/维护者	阻止机器人自动合并此 PR
bot/light-review	维护者	将所需 LGTM 从 2 个降为 1 个

默认情况下执行的是 squash-rebase 合并。bot/light-review 标签适用于以下四类低风险变更：

• 更新依赖（Updating a dependency）；
• 将分支回合并到下一个版本分支（Merge back into next version branch）；
• 提交较小的文档变更；
• 提交 changelog PR。

值得注意的是 .github/PULL_REQUEST_TEMPLATE/ 目录下还有 mergeback.md 与 release.md 两个专用模板，分别服务于"分支回合并"与"版本发布"这两类正是 bot/light-review 适用场景的 PR。

为什么我的 PR 被关闭？

Traefik 强调目标是维护一个精干的代码库并保持开发速度，因此有些 PR 确实无法被合并。指南承诺：无论何种原因，团队都会明确告知关闭理由；而且关闭一个 PR 几乎不会丢失什么工作——重建一个已关闭的 PR 成本很低。PR 可能被关闭的三种情况：

1. 设计冲突：PR 设计与现有代码库冲突到无法通过合并解决的程度，且让 PR 变得可用的改造成本过高。预防方法：先创建 Issue，并在设计阶段拉 Traefik 维护者参与，把冲突消灭在写代码之前；
2. 方向不被采纳：PR 属于一个团队决定不采用的增强或功能。这再次说明"先 Issue 后 PR"的重要性——先确认目标可合并、拿到团队的设计输入；
3. 长期无响应：PR 等待贡献者反馈超过 90 天。

为什么我的 PR 迟迟未被评审？

影响评审等待时间的因素主要有两类。

第一类：优先级排序。 团队的首要优先级是社区参与度高、适用面宽的 PR，即打了 contributor/wanted 标签、列入 roadmap 的条目；次要优先级是缺陷修复，尤其是已打 bug/confirmed 标签的缺陷。不满足上述条件的 PR 自然排队靠后。此外，在每个里程碑的最后几周，团队会停止评审 PR 以减少变动、稳定版本，发布后恢复。

第二类：未遵循最佳实践。 指南列出的最常见扣分项：

• 没有先创建 Issue：没有 Issue，团队就无法回答你的设计问题，也无法告诉你 PR 被合并的可能性；
• PR 过大：应该拆分——能从中抽离出完整想法的，就单独发一个 PR。"多个各解决一件事的 PR"优于"一个解决许多事的 PR"。由于 Traefik 代码库迭代快，指南的建议是尽快用小 PR 锁定你的改动、把合并冲突留给别人处理，并自行判断哪些内容该成为 PR、哪些只是 commit；
• 注释不充分："Comment everything"——评审者来自不同国家与文化背景，不会天然地以你的方式理解问题或解题，所以每处变更及其编码策略都必须被解释；
• 测试缺失或不充分：不知道如何测试就公开提问，团队愿意帮忙或建议合适的测试用例。

如果已经遵循了全部最佳实践仍无响应，指南给出两个推进动作：修完评审意见后用"重新请求评审"按钮正式 re-request review（可附评论说明改动内容）；以及在 PR 上主动评论——评论会自动让 PR 在分诊流程中重新获得可见性。指南最后还推荐了几篇关于 Git commit message 写法的经典文章（Chris Beams 的 "How to Write a Git Commit Message"、Pro Git 书中的 commit guidelines、关于 50/72 字符规则的讨论、Tim Pope 的 "A Note About Git Commit Messages"），建议提交前阅读。

合理表达反对意见

评审者也会犯错。如果你对评审意见有不同看法，完全可以基于充分的理由进行反驳——前提是保持礼貌与尊重。你既可能被说服，也可能说服对方。

指南还提到开源项目中的一个典型现象 dog-pile（评论踩踏）：一个 PR 收到太多人评论导致难以跟进。此时的处理方式是询问主评审人（assignee）：是否希望 fork 出一个新 PR 来清空所有旧评论。规则边界是：你不必修正每个路人都提出的所有问题，但对合理的评论必须给出解释性回复。

AI 辅助代码评审（ai/review 标签）

维护者可以给 PR 添加 ai/review 标签，触发自动化的 AI 代码评审。其工作方式与贡献者预期如下：

触发机制： 标签应用后，一个 AI agent 会读取 diff 以及每个被修改文件的完整内容，然后直接在 PR 上以 inline comment 形式发布评审意见。评审依据的是仓库特定的评审规范，覆盖安全、正确性、破坏性变更、性能与 Go 语言惯例（error wrapping、context 传播、日志、测试风格等）。

预期行为：

• 评论按严重级别分类：CRITICAL、IMPORTANT、MINOR 或 QUESTION；
• agent 在把某处改动标记为"不安全"之前会检查调用点（call sites），经不起调用点核对的结论不会被发布；
• 生成文件、//nolint: 指令、以及代码库中已一致使用的既有模式不会被标记。

如何回应： 把 AI 评审意见当作人类评审者的意见对待即可。如果某条结论错误或不适用于你的改动，就在回复中解释原因——维护者在批准前会阅读每一个讨论串。

常识与礼貌：文档之外的最后一层约定

指南的最后一段点明：没有任何文档能替代常识与品味。用你最好的判断力，并花一点心思让评审工作变得更轻松，你的 PR 就会以更少的摩擦被合并。综合全文，可以把它收敛为一条提交前的自检清单：

1. 先有 Issue（或已在现有 Issue 下表明参与意向），方向确认过；
2. 目标分支正确（功能进 master，修复进对应版本分支），使用了 PR 模板；
3. make generate、make generate-crd、make test-gateway-api-conformance、make validate、make pull-images、make test 全部本地跑绿；
4. PR 小粒度、单问题、充分注释、非 Draft、允许维护者编辑、依赖引用 tag；
5. 提交后保持响应，评审意见修完及时 re-request review；
6. 遇到分歧礼貌辩论，遇到 dog-pile 与主评审人沟通是否需要新 PR。

这套流程的最终落点是 Lobicornis：当 CI 全绿、最小评审数（默认 2 个 LGTM，bot/light-review 时 1 个）满足、且由最终 LGTM 的维护者打上 status/3-needs-merge 标签后，机器人会完成 squash-rebase 自动合并；卡住时以 bot/need-human-merge 标签作为人机交接点。理解这条标签链，贡献者就能准确判断自己处于合并流程的哪一步，以及下一步该做什么。