API网关云原生微服务【免费下载链接】kgatewayThe Cloud-Native API Gateway and AI Gateway项目地址https://gitcode.com/gh_mirrors/kg/kgateway点击查看免费下载kgateway 是一个云原生 API 网关与 AI 网关项目。本文是面向所有贡献者的 PRPull Request提交流程参考指南重点服务于新贡献者与不常提交 PR 的开发者从 DCO 签名合规、提交前本地校验make verify/make analyze、必需 CI 检查到小 PR 更易评审用提交讲故事等实战原则一篇文章带你走通从 commit 到 merge 的全流程。读完本文你将能独立完成一个符合 kgateway 项目规范的 PR并理解其自动化合并机制背后的仓库实现。提交流程合并一个 PR 需要完成哪些步骤在 kgateway 仓库中PR 的合并是自动化的但前提是提交者必须完整走完以下步骤确保每一个 commit 都包含Signed-off-bytrailer以遵守 DCODeveloper Certificate of Origin开发者原始认证要求打开 PR 前运行本地校验命令并修复所有报错打开 Pull Request通过全部必需 CI 检查获得评审者reviewer与代码所有者code owner的审批。下面逐一展开每个步骤的实操细节。第一步为每个 commit 添加Signed-off-bytrailerDCO 合规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幂等地为提交信息追加 trailerNAME$(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 之前建议运行以下两条命令并修复其报告的任何错误命令作用底层实现make verify -B运行代码生成codegen若产生任何本地 diff 则报错见 Makefile 与 Code Generationmake analyze -B运行 linter返回所有 lint 错误见 Makefile-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.mdverify运行 codegen 并在有任何文件变更时报错约 4–5 分钟generate-all/generated-code生成全部所需代码并清洗、格式化CI 中执行的目标go-generate-all包含go-generate-apis与go-generate-mocksAPI 变更时使用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 #123Change Type通过斜杠命令声明变更类型例如/kind feature、/kind fix、/kind breaking_change、/kind deprecation、/kind documentation、/kind cleanup、/kind install、/kind bump另有design、flake、test等不计入 release notes 的类型Changelog提供将出现在发布说明中的确切文案若无需发布说明则写NONEAdditional Notes留给评审者的额外上下文与边界情况说明。第四步通过所有必需 CI 检查kgateway 的 draft PR 与 ready-for-review PR 运行相同的 CI 检查包括端到端与一致性测试。根据 .github/workflows/README.md合并 PR 前必须通过以下检查DCO确保每个 commit 都含Signed-off-bytrailerLabelerlabeler.yaml解析 PR 描述提取变更类型与 changelog 用于发布说明因此 PR 描述必须遵循 PR 模板Lintlint.yaml检查 Go、Rust 代码以及 Helm chart、GitHub workflow 文件的 lint 错误Verifyverify.yaml运行代码生成并确保生成文件与仓库一致Unit Testsunit.yaml运行全部 Go 单元测试Gateway API Conformance Testsconformance.yaml分别在 experimental 与 standard 两条 Gateway API 通道上运行一致性测试使用上游 Kubernetes Gateway API 一致性测试套件Kubernetes End-to-End Testse2e.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 一节评论 / 标签效果限制/retest单独一行触发 retest 任务重新运行 PR 上最新工作流运行中失败的 job仅限 kgateway 组织成员/merge单独一行触发 enable auto-merge 任务为 PR 开启自动合并若所有必需检查已通过且 PR 已获审批会立即将 PR 加入 merge queue即使仍有非必需检查未通过仅限 kgateway 组织成员/unmerge单独一行触发 disable auto-merge 任务关闭自动合并注意PR 已进入 merge queue 后无法通过此命令撤销需请维护者手动移出仅限 kgateway 组织成员do-not-merge*或work in progress标签check-labels 工作流会阻止带这些标签的 PR 被合并任何人均可添加用于防止意外合并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 成单个 commitcommit 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-authorContribution Conventions编码与测试约定Code Generationcodegen 各 Make 目标的细节Adding fields to Policy CRDs扩展 Policy CRD 的端到端工作流Issues提交 issue 的规范注意敏感信息一律走安全通道不要公开提交Documentation产品文档的贡献入口Releasing发布流程与规范。赞分享API网关云原生微服务【免费下载链接】kgatewayThe Cloud-Native API Gateway and AI Gateway项目地址https://gitcode.com/gh_mirrors/kg/kgateway点击查看免费下载相关推荐AnimatedDrawings社区贡献代码提交与Pull Request流程AnimatedDrawings社区贡献代码提交与Pull Request流程 引言加入开源动画革命 你是否曾经想过让手绘的角色动起来AnimatedDr计算机视觉图形学BFE 开源贡献指南提交 Pull Request 的完整流程与最佳实践BFE 开源贡献指南提交 Pull Request 的完整流程与最佳实践 BFEBaidu Front End是一款由百度开源的新一代七层负载均衡器。本文后端网络/通信云原生Flowable-Engine Pull Request指南代码贡献的最佳实践Flowable Engine Pull Request指南代码贡献的最佳实践 你是否在为如何向Flowable Engine提交高质量代码贡献而困惑本文将后端工作流自动化流程编排上一篇如何快速掌握游戏交易流放之路2玩家的终极价格查询与交易助手指南下一篇LaTeX公式转图片终极指南10分钟学会数学公式可视化创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考