企业官网建设流程全解析

• API网关
• 云原生
• 微服务

kgateway 是一个云原生 API 网关与 AI 网关项目。本文是面向所有贡献者的 PR（Pull Request）提交流程参考指南，重点服务于新贡献者与不常提交 PR 的开发者：从 DCO 签名合规、提交前本地校验（make verify/make analyze）、必需 CI 检查，到"小 PR 更易评审""用提交讲故事"等实战原则，一篇文章带你走通从 commit 到 merge 的全流程。读完本文，你将能独立完成一个符合 kgateway 项目规范的 PR，并理解其自动化合并机制背后的仓库实现。

提交流程：合并一个 PR 需要完成哪些步骤

在 kgateway 仓库中，PR 的合并是自动化的，但前提是提交者必须完整走完以下步骤：

1. 确保每一个 commit 都包含Signed-off-bytrailer，以遵守 DCO（Developer Certificate of Origin，开发者原始认证）要求；
2. 打开 PR 前，运行本地校验命令并修复所有报错；
3. 打开 Pull Request；
4. 通过全部必需 CI 检查；
5. 获得评审者（reviewer）与代码所有者（code owner）的审批。

下面逐一展开每个步骤的实操细节。

第一步：为每个 commit 添加Signed-off-bytrailer（DCO 合规）

DCO 要求每个 commit 都必须带有一行Signed-off-bytrailer，用以声明提交者确认对代码的贡献具有相应权利。kgateway 提供了三种合规方式，任选其一：

方式一（推荐）：make init-git-hooks

这是仓库首选的方式。它通过把 Git hooks 指向仓库内受版本控制的 .githooks 目录，让每次git commit自动追加签名。其底层实现位于仓库根目录的 Makefile：

.PHONY: init-git-hooks init-git-hooks: ## Use the tracked version of Git hooks from this repo git config core.hooksPath .githooks

执行后，Git 会将本仓库的.githooks目录作为 hooks 路径。核心逻辑在 .githooks/prepare-commit-msg 脚本中——它读取本地的git config user.name与user.email，再用git interpret-trailers幂等地为提交信息追加 trailer：

NAME=$(git config user.name) EMAIL=$(git config user.email) if [ -z "$NAME" ]; then echo "empty git config user.name" exit 1 fi if [ -z "$EMAIL" ]; then echo "empty git config user.email" exit 1 fi git interpret-trailers --if-exists doNothing --trailer \ "Signed-off-by: $NAME <$EMAIL>" \ --in-place "$1"

值得注意的是：--if-exists doNothing保证了一个 commit 只会有一条签名，重复提交不会叠加；而脚本会检查user.name/user.email是否已配置，未配置时直接报错退出，从源头避免签名失败。

方式二：手动复制 hook 脚本

如果不想全局修改仓库配置，可以直接把 .githooks/prepare-commit-msg 复制到本地副本的.git/hooks/prepare-commit-msg位置，效果与方式一相同，但改动不写入仓库配置。

方式三：每次提交显式使用-s/--signoff标志

即每次执行git commit时带上-s或--signoff参数，Git 会自动生成Signed-off-bytrailer。此方式最直接，但依赖提交者的使用习惯，容易遗漏；仓库因此优先推荐用 Git hooks 自动化。

第二步：打开 PR 前，运行本地校验命令

在创建 PR 之前，建议运行以下两条命令并修复其报告的任何错误：

-B标志强制目标始终执行，不使用 Make 的缓存判断，确保校验结果基于最新代码。

make verify的原理：代码生成必须与仓库同步

kgateway 的代码生成是 CI 的重要一环。verify目标会先强制运行generated-code（其定义见 Makefile），即执行完整的generate-all（包含 API 生成、mock 生成、依赖整理、格式化、license 归因等子目标，各子目标的功能与耗时详见 Code Generation），随后执行：

git diff -U3 --exit-code

如果代码生成导致任何文件发生变更，git diff将非零退出，verify即报错——这通常意味着有生成文件尚未提交。各 codegen 子目标概览（来自 devel/contributing/code-generation.md）：

• verify：运行 codegen 并在有任何文件变更时报错，约 4–5 分钟；
• generate-all/generated-code：生成全部所需代码并清洗、格式化，CI 中执行的目标；
• go-generate-all：包含go-generate-apis与go-generate-mocks，API 变更时使用；
• go-generate-apis：调用 hack 目录下所有 generate 指令，约 1 分钟；
• go-generate-mocks：调用仓库内所有 mockgen 指令，接口 API 变更时使用；
• mod-tidy：调用go mod tidy，依赖增删改时使用；
• fmt：运行 golangci-lint 的gci格式化器整理 import 并格式化代码；
• generate-licenses：为需要归属说明的依赖生成文档，新增依赖或升级依赖时使用。

make analyze的原理：仓库级 lint 检查

analyze目标先对仓库全部 YAML 执行fmt-yaml（使用go tool -modfile tools/go.mod yamlfmt，见 Makefile），再运行 golangci-lint 自定义构建（$(CUSTOM_GOLANGCI_LINT_RUN) $(ANALYZE_ARGS) ./...）扫描全部 Go 代码。可通过ANALYZE_ARGS变量覆盖 golangci-lint 的默认选项。

第三步：打开 Pull Request

本地校验通过后，即可创建 Pull Request。仓库为 PR 提供了标准模板 .github/PULL_REQUEST_TEMPLATE.md，其结构直接对应下文的 PR Body 指南：

• Description：包含 Motivation（为什么需要这个改动）、What changed（关键实现细节）、Related issues（如Fixes #123）；
• Change Type：通过斜杠命令声明变更类型，例如/kind feature、/kind fix、/kind breaking_change、/kind deprecation、/kind documentation、/kind cleanup、/kind install、/kind bump；另有design、flake、test等不计入 release notes 的类型；
• Changelog：提供将出现在发布说明中的确切文案，若无需发布说明则写NONE；
• Additional Notes：留给评审者的额外上下文与边界情况说明。

第四步：通过所有必需 CI 检查

kgateway 的 draft PR 与 ready-for-review PR 运行相同的 CI 检查（包括端到端与一致性测试）。根据 .github/workflows/README.md，合并 PR 前必须通过以下检查：

• DCO：确保每个 commit 都含Signed-off-bytrailer；
• Labeler（labeler.yaml）：解析 PR 描述，提取变更类型与 changelog 用于发布说明，因此 PR 描述必须遵循 PR 模板；
• Lint（lint.yaml）：检查 Go、Rust 代码以及 Helm chart、GitHub workflow 文件的 lint 错误；
• Verify（verify.yaml）：运行代码生成并确保生成文件与仓库一致；
• Unit Tests（unit.yaml）：运行全部 Go 单元测试；
• Gateway API Conformance Tests（conformance.yaml）：分别在 experimental 与 standard 两条 Gateway API 通道上运行一致性测试，使用上游 Kubernetes Gateway API 一致性测试套件；
• Kubernetes End-to-End Tests（e2e.yaml）：运行 test/e2e 下的端到端测试套件。

此外，项目还通过每晚定时工作流（nightly-tests.yaml）对main和每个受支持的 LTS 分支运行一致性、负载与 e2e 测试。

第五步：获得评审者与代码所有者审批

提交 PR 后，维护者（maintainer）会在 PR 上启动自动化（若你还不是组织成员）并提供评审。只有当所有必需检查通过、且获得足够的 reviewer 与 code owner 审批后，PR 才会被自动合并。评审相关的沟通原则详见 Pull Request Reviews。

与 CI 交互：注释命令与合并保护标签

kgateway 允许通过 PR 评论和标签与 CI 交互（详见 .github/workflows/README.md 的 "Interacting with CI" 一节）：

PR 最佳实践：让评审更快、更彻底

以下是 kgateway 社区在实践中总结出的、能让 PR 快速得到评审的经验。

遵循项目约定

提交代码前，请先阅读 Coding conventions。该文档覆盖编码约定（如 Go 的 Effective Go、注释规范、错误变量以Err开头、错误类型以Error结尾）、API 约定（见 api/README.md）、IR 约定（KRT collection 输出的 IR 必须实现Equals方法并配套单元测试）、测试约定以及目录与文件命名规范（如 Go 源文件用下划线、文档目录用短横线）。

小而精：小 PR 更易被彻底评审

小 PR 更容易被快速、彻底地评审。经验表明：如果一个 PR 的评审时间超过 45 分钟，评审质量可能会下降，更容易漏掉重要问题。因此宁可拆分为多个小 PR，也不要一次提交巨型改动。

用 commit 讲清楚故事

一系列离散的 commit 能让评审者更容易理解 PR 的意图，并把评审拆解为更小的块。特别提醒：kgateway 在合并 PR 时会将其squash 成单个 commit（commit message 即 PR 标题），因此你无需在合并前自行 squash。

避免 squash 之前的 commit 与 force push

反复改写历史会让人难以理解 PR 的发展脉络，也会给日后追溯变更带来困难。除非必要，请不要对已推送的 commit 做 squash 或 force push。

分离特性改动与通用性修复

如果你顺手发现了一些与本次改动无关的"表面问题"（拼写错误、格式问题、不理想的命名等），请作为单独的 PR提交，不要混入当前特性 PR。当然，一切以你的判断为准：少量小改动没问题，但如果发现自己改了太多无关文件，最好拆分开。

尽早收集反馈

如果你的改动很大，或对技术方案没有把握，尽早征求意见。方式包括：打开一个draft PR，或在 CNCF Slack 的 kgateway 频道中提问。早反馈能避免在错误方向上走太远。

注释更重要：解释"为什么"，而不是"怎么做"

在代码中，如果某个做法可能让人困惑，那么日后更不会有人记得当时为什么这么做。因此要写注释来表达why（原因），因为代码本身已经表达了how（怎么做）。注释风格建议遵循 Go 的 GoDoc 注释规范。

测试：几乎每个改代码的 PR 都必须附带测试

几乎每个修改代码的 PR，都应该同时修改或引入测试。如果你的 PR 确实不适用（例如纯文档改动），请在 PR body 中说明原因。如果你不清楚如何为某个特性编写测试，请直接提问，维护者很乐意建议合适的测试用例。仓库测试约定详见 writing tests。

PR Body 指南：让评审者第一时间获得上下文

PR 描述通常是评审者获取变更上下文的第一来源，建议做到：

• 在 PR body 中描述变更，把 why 讲清楚，便于日后理解；
• 逐条列出所有变更（尤其是一些小改动），让评审者确认这些改动都是有意为之；
• 在 PR body 中链接相关的 Slack 讨论或设计文档，避免上下文丢失。

一个额外的关键细节：由于 kgateway 合并时会把改动 squash 成单个 commit、其 message 即 PR 标题，所以一个能清晰描述变更的标题非常重要。仓库的设计文档目录 design 中保存了大量 RFC（如 "Policy Application and Merging"、"Route Delegation" 等），需要时可作为背景链接进 PR。

延伸阅读

• Pull Request Reviews：评审视角的最佳实践，包括如何提问、标注 nit、请求变更、审批与共同责任（approve 意味着你将成为该改动的 co-author）；
• Contribution Conventions：编码与测试约定；
• Code Generation：codegen 各 Make 目标的细节；
• Adding fields to Policy CRDs：扩展 Policy CRD 的端到端工作流；
• Issues：提交 issue 的规范，注意敏感信息一律走安全通道，不要公开提交；
• Documentation：产品文档的贡献入口；
• Releasing：发布流程与规范。

• API网关
• 云原生
• 微服务