提交拉取请求之前¶

本指南面向已经准备好提交拉取请求的贡献者。 如果你需要了解如何搭建开发环境， 以及如何编写代码为 Traefik Proxy 或相关项目做贡献， 请参阅开发指南。

正在寻找为 Traefik Proxy 贡献的机会？ 可以查看优先议题、 适合首次贡献的议题， 或等待修复的已确认缺陷。

我们如何安排优先级¶

我们希望立即审查每一个拉取请求，但审查需要时间，无法总是做到。

以下拉取请求通常处理最快：

• 文档更新。
• 缺陷修复。
• 带有 contributor/wanted 标签的改进与新功能。

以下拉取请求需要更多时间：

• 没有 contributor/wanted 标签的改进或新功能。

如果你有想实现的改进或新功能， 先为它创建议题， 并告诉我们你有兴趣编写拉取请求。 如果议题已经存在，也务必留言说明你希望提交拉取请求。

这样我们就能直接沟通，并告诉你团队是否会接受这项工作。

也能在设计阶段确保你掌握全部必要信息， 使后续审查和合并更快完成。

更多信息请阅读议题分流流程。

拉取请求提交流程¶

拉取请求在自动合并之前，需要完成以下步骤：

• 确保拉取请求符合最佳实践，包括：
  • 遵循项目约定，包括使用拉取请求模板。
  • 保持拉取请求规模较小。
  • 每次只解决一个问题。
  • 提供充分注释。
  • 不要从组织仓库发起拉取请求。
  • 保持勾选“允许维护者编辑”。
  • 文档使用语义化换行。
  • 确保拉取请求不是草稿。我们不审查草稿，但会根据需要回答问题并与开发者讨论。
  • 确保 go.mod 中的依赖引用标签。如果无法引用标签，应添加注释解释原因。
• 通过验证检查。
• 通过全部测试。
• 获得两位维护者的批准审查。

拉取请求审查周期¶

可以了解我们的议题分流流程， 其主要过程如下：

• 每个新拉取请求或评论在进入审查流程之前，都会先经过分流。
  • 确认满足审查的全部前置条件。
  • 检查使用场景是否符合项目需求。
  • 分配审查者。
• 设计审查。
  • 这一阶段比流程中的其他部分耗时更多。
  • 检查设计与现有代码库之间是否存在明显冲突。
• 代码审查。
  • 深入审查代码并运行测试。
  • 这一阶段可能要求修改。
  • 代码审查期间，希望你能够及时回应。 如果拉取请求长期停滞在审查阶段，可能被拒绝， 也可能由我们接手，此时原贡献者会成为共同作者。
  • 维护者可以添加 ai/review 标签，触发自动化 AI 拉取请求审查。 审查基于仓库专属指南，并通过行内评论发布。
• 合并。
  • 完成！

运行本地验证¶

提交拉取请求之前，必须运行以下本地验证，以预判持续集成能否通过。 只有 CI 中这些检查全部通过后，拉取请求才会进入审查。

• make generate
• make generate-crd
• make test-gateway-api-conformance
• make test-gateway-api-conformance-merged
• make validate
• make pull-images
• make test

测试与合并工作流¶

拉取请求由机器人 Myrmica Lobicornis 管理。 它负责检查 GitHub Checks（CI、测试等）、可合并状态以及最低审查数量。 必要时，还会针对拉取请求的目标分支执行变基或合并。 它还执行一些其他维护操作， 详情可阅读 Lobicornis 的 README。

给出最终 LGTM 的维护者必须添加 status/3-needs-merge 标签，触发合并机器人。

默认执行 squash-rebase 合并。

status/4-merge-in-progress 状态仅由机器人使用。

如果机器人无法合并，会添加 bot/need-human-merge 标签。 此时应解决冲突、CI 等问题，然后移除 bot/need-human-merge 标签。

若要阻止机器人自动合并拉取请求，添加 bot/no-merge 标签。

bot/light-review 标签会将所需 LGTM 数量从 2 降到 1。

以下情况可使用该标签：

• 更新依赖。
• 将分支合并回下一个版本分支。
• 提交小幅文档修改。
• 提交变更日志拉取请求。

为什么我的拉取请求被关闭？¶

Traefik Proxy 由社区构建，也服务于社区， 目标是让社区共同打造出色的反向代理。 保持精简代码库和开发速度，也是这个目标的一部分。 遗憾的是，这意味着有些拉取请求无法合并。

我们尊重你投入的工作，因此总会说明关闭拉取请求的原因。 如果你不同意这个决定，也不用担心：关闭的拉取请求很容易重新创建， 关闭后再重新打开，不会损失多少工作。

以下情况可能导致拉取请求被关闭：

• 拉取请求的设计与现有代码库冲突，无法直接合并， 且将它改到可用状态所需的工作量过大。
  • 为避免这种情况，先创建议题， 并考虑在设计阶段邀请 Traefik Proxy 维护者参与，以减少冲突。
• 拉取请求实现的是项目不会采用的改进或功能。
  • 记住：创建拉取请求之前先为它创建议题， 确认目标能够合并，并获得团队提供的必要设计建议。
• 拉取请求等待贡献者反馈超过 90 天。

为什么我的拉取请求尚未得到审查¶

多种因素会影响拉取请求等待审查的时间。

我们必须安排审查重点。 首要优先级是已经确认具有较高社区参与度和广泛适用性的拉取请求。 这些最高优先事项会列入路线图，并使用 contributor/wanted 标签标识。 这类拉取请求会最快进入审查流程。

第二优先级是缺陷修复， 尤其是已标注 bug/confirmed 的缺陷。 这些审查也会较快进入流程。

如果拉取请求不符合上述条件， 审查所需时间就会更长，因为符合条件的拉取请求会优先处理。

此外，在某个里程碑的最后几周，我们会停止审查拉取请求，以减少变动、稳定版本。 发布后恢复审查。

拉取请求被降低优先级的另一个主要原因是没有遵循最佳实践。

最常见的问题包括：

• 没有先为计划中的拉取请求创建议题。 如果提交拉取请求前没有议题， 我们就无法提前回答设计问题，也无法告诉你它被合并的可能性。
• 拉取请求过大，难以审查。
  • 将拉取请求拆小。 如果能从拉取请求中抽出完整、独立的想法，分别作为拉取请求提交， 就应该这样做。 多个各解决一件事的拉取请求，优于一个解决许多事的拉取请求。
  • Traefik Proxy 的代码库发展很快，因此应尽快通过小型拉取请求确定你的变更， 让后续合并成为其他人的工作。 我们希望每个拉取请求都能独立产生价值， 因此请自行合理判断哪些内容应拆为拉取请求，哪些只需拆为提交。
• 注释不充分。
  • 为各项内容提供注释。

记住，我们的协作跨越国家、文化和不同使用场景。 审查者未必能像你一样直观地理解问题，也未必采用相同的解决方式。 因此，你必须解释每项变更，也必须解释编码策略。

• 测试不足或没有测试。
  • 如果不知道如何测试拉取请求，请提问！ 我们很乐意帮助你，或建议合适的测试用例。

如果已经遵循最佳实践，但拉取请求仍未得到回应， 可以通过以下方式推动流程：

• 修复审查提出的全部问题后， 记得使用指定按钮重新请求审查，让审查者知道已经准备好。 也可以留言说明所作修改。
• 礼貌地在拉取请求中留言。这会在分流过程中自动让维护者再次注意到它。

更多最佳实践可参考：

• 如何编写 Git 提交信息——Chris Beams
• 分布式 Git：向项目贡献（提交指南）
• 50/72 规则是什么？——Preslav Rachev
• 关于 Git 提交信息的一点说明——Tim Pope

可以提出不同意见¶

审查者有时也会犯错。 对审查者要求的修改提出异议完全可以。 如果你有充分理由采用某种实现方式，就可以讨论所要求修改的利弊。 审查双方都应以礼貌、尊重的方式讨论这些问题。

你的意见可能被否决，也可能获得认同。 我们都是愿意讲道理的人。

开源项目允许任何人评论任何议题，因此还可能出现评论蜂拥而至的情况： 拉取请求收到太多人的太多评论，导致讨论难以跟进。 这时可以询问主要审查者（负责人），是否希望另开拉取请求， 以清理已有评论。 你不必修复每个评论者提出的每个问题， 但应对合理评论给出解释。

AI 辅助代码审查¶

维护者可以为拉取请求添加 ai/review 标签，触发自动化 AI 代码审查。

标签添加后，AI 代理会读取差异和所有修改文件的完整内容， 然后直接在拉取请求上发布行内评论。 审查遵循仓库专属指南，覆盖安全性、正确性、不兼容变更、 性能和 Go 约定，包括错误包装、上下文传递、日志、测试风格等。

你会看到：

• 评论按严重程度分类：CRITICAL、IMPORTANT、MINOR 或 QUESTION。
• 代理在判定变更不安全之前会检查调用点；无法通过该检查的问题不会发布。
• 生成文件、//nolint: 指令以及代码库中已一致使用的模式不会被标记。

如何回应：

将 AI 审查评论视为人工审查者的评论。 如果某项发现不正确或不适用于本次变更，请回复解释；维护者在批准之前会阅读每个讨论串。

常识与礼貌¶

任何文档都不能取代常识与良好的技术品味。 运用自己的判断，同时思考怎样让工作更容易被审查。 做好这些，拉取请求就能更顺利地合并。