Envoy 贡献者指南从 PR 规范到运行时守护与废弃策略的完整实战手册【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoyEnvoyCONTRIBUTING.md是面向社区开源的云原生高性能边缘/中间/服务代理任何开发者都可以提交 PR 参与共建。本文以仓库根目录的贡献指南为骨架系统梳理 Envoy 的沟通约定、编码与包容性语言规范、生成式 AI 使用边界、破坏性变更含 API 版本化与废弃特性淘汰策略、PR 提交流程、运行时守护Runtime Guard机制、扩展/contrib 扩展新增流程、DCO 签名与 CI 重跑技巧并结合仓库内真实源码、测试与配置文件给出可验证的实战细节。读完本文你将掌握从提交第一个小修复到引入一个被运行时守护的重大特性的完整路径也能理解 Envoy 社区如何通过多阶段废弃策略保护部署在生产环境中的用户。一、提交前的沟通约定避免返工的第一道关卡Envoy 社区对重大特性有明确界定任何改动超过100 行不含测试或改变任何用户可见行为的变更都算重大特性。对于这类变更官方要求在动手前通过 GitHub、Slack、邮件等方式联系社区确认没有人正在做同样的事并按要求打开 GitHub issue社区会借助 issue 讨论特性设计并达成一致防止双方浪费时间如果合适应编写设计文档文档必须托管在 GitHub issue 中或由 issue 链接到世界可读的位置特别地如果目标是新增一个扩展必须先阅读扩展策略小补丁和 bug 修复不需要事先沟通可以直接提交。从扩展策略可以进一步看到新增扩展还需要满足由现有维护者赞助sponsorship、提出两名非高级维护者的评审人将写入 CODEOWNERS、遵循 DEPENDENCY_POLICY.md 依赖策略等硬性要求——这些都应在提交前评估清楚。二、编码风格与包容性语言规范2.1 编码风格所有代码必须遵循 STYLE.md。Envoy 的编码风格覆盖 C/protobuf/文档等多个维度是 CI 中格式检查format check的判定依据。2.2 包容性语言政策Envoy 社区明确以包容所有人为目标所有代码、API 和文档中禁止使用以下词汇禁止词替代词WhitelistallowlistBlacklistdenylist 或 blocklistMasterprimary 或 mainSlavesecondary 或 replica文档应采用包容性文风维护者在 code review 时也会就此类问题给出意见该政策并非最终版本会随行业最佳实践演进而修订。三、生成式 AI 使用政策被允许但责任在提交者Envoy 是较早明确制定生成式 AI 政策的大型开源项目之一核心原则是AI 是辅助责任在人类。3.1 AI 辅助写代码五项硬性要求提交者必须完全理解所提交的代码提交者必须回应评审者的提问与评论如果用 AI 生成回复必须编辑并校对 AI 输出确保回复合理评审者要求修改时提交者必须有能力修改 AI 生成的代码即使 AI 助手做不到责任仍在提交者提交者必须透明披露AI 使用情况建议在 PR 描述中注明使用了 AI 工具所有生成代码必须以与 Envoy 相同的 LICENSE 发布提交者要确保所用工具不会附加额外的许可限制。3.2 AI 辅助评审两条要求必须删除或解决 AI 评审代理产生的幻觉式、低价值评论必须回应用户对 AI 评论的澄清请求或异议并建议主动说明为何需要处理 AI 生成的评论。3.3 禁止事项提交者不理解、不承担全部责任的 PR只对 AI 交互有帮助、对代码库无价值的代码注释能解释直白代码在做什么的注释没有意义必须在提交前删除在 PR 上路过式地调用 AI 评审代理却不打算跟进评审结果。四、破坏性变更政策与废弃Deprecation机制API 与实现的稳定性对 Envoy 至关重要。API 被外部客户端消费有独立的版本化指南本节阐述实现层面的稳定性规则它们运行在 API 版本化指南的框架之内。4.1 版本化与兼容性原则从 api/API_VERSIONING.md 可以提取关键背景Envoy API 由一系列独立版本化的 protobuf 包组成如envoy.admin.v3alpha、envoy.service.trace.v3大版本号体现在包名与目录结构中如envoy.service.trace.v3位于api/envoy/service/trace/v3在一个包的大版本内不允许任何破坏性变更字段不得重新编号或改类型不得重命名字段或包命名空间会破坏 YAML/JSON/text proto 加载且 gRPC 端点 URL 由包命名空间推断即使是通常被认为安全的变更在 Envoy 中也被视为破坏性单例字段升级为 repeated改变 JSON wire 表示、用oneof包裹现有字段、收紧 protoc-gen-validate 注解例外字段/消息引入 14 天内且未进入任何 Envoy 发布版本、vNalpha版本内、带work_in_progress注解的 proto实际上 v3 已成为最终大版本不会再有版本大升级字段永远不会被删除废弃仅作为推荐更优配置方式的提示但实现会一直保留。4.2 实现层面的多阶段废弃流程尽管字段永不删除Envoy 仍通过警告 → 失败 → 清理实现的节奏管理废弃特性实现代码会在下个大 API 版本后移除特性可在任意时间点被标记废弃但前提是 main 分支上已存在替代实现与配置路径废弃者必须实现从废弃配置到 Envoy 内部使用的最新vNalpha配置的转换工具移除字段以描述 HTTP/2 窗口设置而引入更全面的 HTTP/2 协议选项字段作为替代——这就是合法废弃的典型例子废弃旧配置的 PR 作者必须更新所有测试与规范配置或用DEPRECATED_FEATURE_TEST()宏保护它们bazel.compile_time_optionstarget 会做硬性校验使用废弃配置将直接构建失败大部分测试与配置应基于最新内部配置vNalpha表达只有验证配置翻译所需的最少测试才用DEPRECATED_FEATURE_TEST()宏守护废弃跨大版本删除例如 v2 中标记废弃的字段会在 v3 中移除。4.3 警告 → 失败 → 移除 的时间线废弃后的第一个发布周期使用该特性会记录日志警告并递增运行时统计runtime.deprecated_feature_use第二个发布周期使用废弃配置会导致配置加载失败除非在运行时配置中显式覆盖参考 configs/using_deprecated_config.yaml 的示例或设置envoy.features.enable_all_deprecated_features为 true废弃的 API 大版本结束后整个实现代码从 Envoy 实现中移除若启用运行时键envoy.features.fail_on_any_deprecated_feature使用废弃字段将直接触发配置加载失败而非警告该政策保证部署 main 的组织在下一个大版本前有准备时间通常是至少12 个月或直到组织迁移到下一大版本。4.4 可验证的测试依据在 test/common/protobuf/utility_test.cc 中DeprecatedFieldsTest系列测试完整覆盖了上述机制IndividualFieldDeprecatedEmitsError废弃字段在非 fatal 模式下记录警告并递增runtime_deprecated_feature_use与deprecated_feature_seen_since_process_start统计IndividualFieldDeprecatedEmitsCrash启用envoy.features.fail_on_any_deprecated_feature后同一检查变为抛异常IndividualFieldDisallowedWithRuntimeOverride通过envoy.deprecated_features:type.field运行时覆盖将 fatal 错误降级为警告IndividualFieldDisallowedWithGlobalOverrideenvoy.features.enable_all_deprecated_features true同样将错误降级为警告DisallowViaRuntime反过来用运行时覆盖把非 fatal 字段升级为异常且该异常优先级高于全局覆盖。4.5 真实废弃配置示例configs/using_deprecated_config.yaml 展示了一个完整的、通过layered_runtime覆盖两个废弃特性的可用配置通过envoy.deprecated_features:envoy.config.trace.v2.ZipkinConfig.HTTP_JSON_V1和envoy.deprecated_features:envoy.api.v2.route.CorsPolicy.allow_origin两个运行时键让对应废弃配置继续生效。4.6 其他边界破坏性变更政策同样适用于源码级扩展如过滤器符合公共接口文档的代码在废弃窗口内应能继续编译运行窗口内应谨慎记录废弃警告某些特性可能需要限流日志对依赖未文档化行为的代码不做任何保证详见扩展移除策略所有废弃/破坏性变更都会清楚列在版本历史docs 目录中高风险废弃可能通过 envoy-announce 邮件列表公告但默认多阶段默认警告/默认失败机制已足以提醒用户迁移鉴于其关键性严格禁止改变 ext_authz 与 ext_proc 协议的默认行为如果一个提交废弃了某特性commit message 必须说明废弃内容并在deprecated区段添加带字段/消息 RST 链接的 release note fragment。五、提交 PR 的完整流程5.1 前置准备Fork 仓库安装 git hooks在本地仓库根目录运行./support/bootstrap该命令安装实现各种重要 pre-commit / pre-push 检查的 git hooks详见 support/README.md。从 support/hooks/pre-push 源码看它会在 push 前自动执行 DCO 与格式检查并支持通过NO_VERIFY环境变量跳过support/README.md 还说明可用git commit --no-verify跳过提交钩子或通过echo NO_VERIFY1 .env持久化。5.2 PR 内容要求新增代码必须附带覆盖新代码的测试草稿 PR 可能不会被评审或 triage想要及时评审就不要创建 draft PR测试会自动运行任何未通过测试的 PR 都不会被合并PR 预期对新增代码有100% 测试覆盖率可通过 coverage build 验证无法达到必须明确说明原因任何改变用户可见行为的 PR 必须同时在 docs 中关联文档并在 changelogs/current 中添加 release note fragmentfragment 放入最合适的区段目录使用 changelogs/changelogs.yaml 列出的规范区段与领域文件名形如area__short-description.rst例如http__added-new-request-stat.rst。从 changelogs/changelogs.yaml 可见合法区段包括behavior_changes、minor_behavior_changes、bug_fixes、removed_config_or_runtime、new_features、deprecated且文件名中/必须编码为~若一个变更适用于多个区段记在最重要的第一个区段例如引入不兼容行为的 bug 修复应记在behavior_changes而非bug_fixesAPI 变更应按 api 贡献指南 在 proto 内联文档化所有代码注释与文档要求正确的英文语法与标点。5.3 PR 标题、提交信息与描述PR 标题应具描述性通常以子系统名加冒号开头例如docs: fix grammar error、http conn man: add new featurecommit message 会在合并时被用作最终提交信息评审过程中若 PR 发生分叉应及时更新PR 描述应说明 PR 做什么如果修复已有 issue以Fixes #XXX结尾若 PR 基于其他贡献者合著用Co-authored-by: name nameexample.com署名。5.4 评审期间的红线一旦进入评审不要 rebaserebase 后需要 force pushGitHub 界面会迫使评审者从头评审整个 PR而无法只看最新改动直接添加新提交或 merge 更利于评审最终合入时会 squash因此 PR 内提交数量无关紧要若需拉取最新改动官方推荐branch$(git status|head -1|cut -f3 -d\ ) git checkout main git pull git checkout $branch git merge main除非修复 DCO否则不要 force pushPR 打开后应被积极维护直至合并或关闭连续7 天无进展的 PR 可能被关闭之后可重新打开这有助于社区管理在途工作。六、运行时守护Runtime Guard高风险变更的标准做法6.1 何时需要运行时守护某些 Envoy 变更被认为值得运行时守护不直接替换旧代码而是在一个 Envoy 发布周期若因性能考虑而守护到完整废弃周期若为高风险行为变更内同时支持两条代码路径。社区通常守护高风险变更如替换 Envoy buffer 实现这类大型重构和大多数用户可见的非配置守护协议处理变更如新增/修改 HTTP 头或 HTTP 序列化方式。不确定时可在 PR 中 envoyproxy/maintainers。6.2 规范写法运行时守护一个特性的规范方式if (Runtime::runtimeFeatureEnabled(envoy.reloadable_features.my_feature_name)) { [new code path] } else { [old_code_path] }以envoy.reloadable_features.前缀命名的守护特性必须能在运行中的 Envoy 实例上安全地翻转 true/false。某些场景下更适合在对象创建时把值锁存到成员变量bool use_new_code_path_ Runtime::runtimeFeatureEnabled(envoy.reloadable_features.my_feature_name)这仅适用于对象生命周期相对于大多数 Envoy 实例较短的情况如Http::ConnectionManagerImpl或Network::ConnectionImpl创建时锁存从而保证运行时值翻转后新行为会被执行、旧行为会随时间自然衰减。6.3 默认值与清理节奏守护特性可在初始 PR、测试间隔后或下一个发布周期默认设为 true由作者与评审维护者酌情决定一般所有运行时守护特性在发布裁剪release cut时都会设为 true重构类旧代码路径在发布并经过一段时间生产运行后可清理行为变更类旧代码若 6 个月内无 Envoy 运营者提出异议则弃用若行为变更对用户造成问题维护者团队会寻求解决方案通常以永久配置开关形式提供行为差异。6.4 源码级证据运行时特性默认置 true 的注册表在 source/common/runtime/runtime_features.cc每个特性对应一个RUNTIME_GUARD(name)宏默认 true或FALSE_RUNTIME_GUARD(name)默认 false命名约定为将envoy_reloadable_features_my_feature_name宏名映射为运行时键envoy.reloadable_features.my_feature_name。文件中还有大量说明性注释如enable_batch_aware_update的注释解释了守护背后的跨线程批量更新动机。真实 release note 示例见 changelogs/current/behavior_changes/local_ratelimit__shadow-mode-descriptor-short-circuit.rst其中说明了如何通过把envoy.reloadable_features.local_ratelimit_shadow_mode_no_short_circuit设为 false 回退修复后的行为。6.5 四种推荐的测试方案创建 per-test 的Runtime::LoaderSingleton参考DeprecatedFieldsTest.IndividualFieldDisallowedWithRuntimeOverride位于 test/common/protobuf/utility_test.cc创建参数化测试parameterized test在测试 setUp 中按GetParam()显式设置新运行时值用自定义运行时默认值搭建集成测试参见集成测试 README显式设置新运行时值为 true/false 运行某个单元测试参考runtime_flag_override_test。运行时代码与普通 Envoy 代码要求相同新旧两条路径在特性默认 true 和 false 两种情况下都应有 100% 覆盖率。6.6 release note 必须说明回退方式新增运行时守护特性时changelogs/current 中的 release note fragment 必须同时包含功能变更与回退方法例如HTTP request header validation is now performed before route selection. This behavioral change can be temporarily reverted by setting runtime guard envoy.reloadable_features.http_validate_headers_before_route_selection to false.七、面向维护者的 PR 评审政策评审通常在一个工作日内完成当前维护者列表见 OWNERS.md核心代码的每个 PR 一般需一位高级维护者评审仅触及测试、扩展、工具、文档或注释的变更只需维护者或高级扩展维护者评审一般还期望代码领域的领域专家参与评审不必有提交权限新增扩展/特性至少有一个批准来自与 PR 作者不同的组织如 Lyft 作者的 PR 至少一个批准者来自其他组织避免组织特有捷径进入代码HTTP/3 新特性因领域专家集中于单一公司可大体豁免但影响通用功能的 HTTP/3 变更仍需跨公司检查contrib 扩展只需 contrib 所有者评审加维护者盖章即可合并不确定评审人选时在 Slack 讨论任何人都可评审任何 PR合并前请清理标题与正文默认 squash merge 会用原标题与每个单独 commit 组成正文执行合并的维护者应确保标题符合上述规范并用 PR 原始 commit message 覆盖正文必要时清理同时保留作者最终的 DCO 签名PR 包含废弃/破坏性变更时应通知 envoy-announce 邮件列表。八、API 变更与新增扩展8.1 API 变更改动 api 树中的任何内容前请阅读 api/review_checklist.md确保变更已处理清单中的全部考量。8.2 新增普通扩展以现有扩展为起点扩展配置应位于类似api/envoy/extensions/area/plugin/的目录结构例如api/envoy/extensions/access_loggers/file/扩展代码应位于对应的source/extensions/area/plugin下包含一个带配置并标记合适安全姿态security posture的envoy_cc_extension以及一个envoy_cc_library更多细节参考 api/STYLE.md。8.3 新增 contrib 扩展详见 EXTENSION_POLICY.md主要差异API 文件放在api/contrib/envoy/但 proto 命名空间仍与普通扩展一致便于日后提升为核心扩展时移动文件构建配置与元数据应纳入 contrib/contrib_build_config.bzl 与 contrib/extensions_metadata.yaml在docs/root/api-v3/config/contrib/contrib.rst添加入口维护者对 contrib 扩展是否被接受有最终决定权可能要求修改或补充文档一个参考准则是提议的 contrib 必须不止对贡献者本人有用。九、DCO 签名为每一次提交签名画押Envoy 要求所有提交满足 Developer Certificate of OriginDCO1.1。签注是在每个 git commit message 末尾的一行Signed-off-by: Joe Smith joegmail.com必须使用真实姓名不接受化名或匿名贡献。certificate 的完整内容条款 a–d在 CONTRIBUTING.md 中核心含义是贡献全部或部分由你创作且你有权提交或基于先前已获许可的工作并有权以其许可证提交或由他人符合 a/b/c 条款直接提供且未修改你理解并同意本项目与贡献是公开的记录将被无限期保留。9.1 自动签注Envoy 自带 commit hooks 可自动生成 DCO 签注行——在项目根目录运行./support/bootstrap之后正常 commit 即可看到每个 commit 底部自动追加 signoff。也可手动添加git commit -s或配置 git 别名让常用命令自动带签注git config --add alias.amend commit -s --amend git config --add alias.c commit -s9.2 修复 DCO若 PR 未通过 DCO 检查需要修复整个 commit 历史最佳实践是 squash 为单个 commit、追加 DCO 签注并 force push。例如历史中有 2 个 commitgit rebase -i HEAD^^ (interactive squash DCO append) git push origin -f注意这种历史重写通常妨碍评审流程仅用于纠正 DCO 错误。9.3 CI 重跑技巧在 PR 中添加包含/retest的一行评论可仅重建 Azure pipelines 中失败的任务若任务卡住未被标记为失败可推送空 commit 重跑全部 CI建议在.gitconfig中添加别名[alias] kick-ci !git commit -s --allow-empty -m Kick CI git push之后执行git kick-ci即可重新触发测试。十、仓库礼仪拥有 Envoy 项目 push 权限的贡献者应优先将改动推送到个人 fork包括创建 PR 分支时。这有助于保持 Envoy 仓库尽可能精简加速所有开发者与 CI 的克隆与同步操作。小结一份通往合入的贡献检查清单变更 100 行或触及用户可见行为先发 issue 并达成共识遵守 STYLE.md、包容性语言政策与 api/API_VERSIONING.md使用 AI 则透明披露并承担全部责任新增代码 100% 测试覆盖改变用户行为则补文档 changelog fragment高风险变更用envoy.reloadable_features.*运行时守护并在 release note 中说明回退方式运行./support/bootstrap安装 hooks提交时确保 DCO signoff评审期间不 rebase、不 force push保持 PR 活跃合并前由维护者清理标题与正文。按照以上路径从一行文档修复到被运行时守护的协议级重构你的贡献都能以符合 Envoy 社区规范的方式合入主干并被数万生产实例安全地消费。【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考