Envoy Mobile 贡献指南协作流程、PR 规范与 DCO 签名机制详解【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy本文基于 Envoy 仓库中 mobile/CONTRIBUTING.md 的贡献规范展开系统梳理 Envoy MobileEnvoy 的移动端子项目社区协作的完整规则链从重大功能先沟通的通信约定、多语言代码风格与包容性语言策略到 PR 提交清单、维护者评审政策再到 DCODeveloper Certificate of Origin签名的自动化实现与修复方法。读完本文你将掌握向 Envoy Mobile 提交 PR 的全部实操要点并能借助仓库内真实的 git hooks 源码support/bootstrap、support/hooks/prepare-commit-msg、support/hooks/pre-push理解签名机制的底层原理让每次提交都顺利通过 DCO 检查与 CI。一、通信约定什么改动需要先打招呼贡献规范对何时需要事前沟通给出了量化标准这是避免重复劳动的关键条款重大功能major feature的定义任何超过 100 行代码LOC的改动不含测试或任何改变用户可见行为的变更。在动手前应先通过 GitHub、Slack、邮件等渠道联系维护团队并开一个 GitHub issue 来讨论设计达成一致后再实施。设计文档要求如果功能适合写设计文档文档必须托管在 GitHub 跟踪 issue 内或链接自 issue 并托管在一个公开可读的位置。小补丁豁免小型补丁与 bug 修复不需要事前沟通可以直接提 PR。规范同时指出重大功能的 GitHub 评审流程也是为了拥有 commit 权限的组织能在设计上达成一致。关于谁是维护者、谁是领域专家可参考 OWNERS.md——该文件列出了全部活跃维护者及其专长领域如 HTTP/3、Bazel/CI、TLS 等可用于把 PR 和提问路由到正确的人。二、代码风格与包容性语言策略代码风格以 mobile/STYLE.md 为准mobile/CONTRIBUTING.md 将编码风格指向 mobile/STYLE.md其中明确了各语言栈的检查工具链语言/类别检查工具规则文件本地运行方式通用文件风格如文件末尾换行pre-commit.pre-commit-config.yamlpre-commit run --all-filespre-commit install装为 commit hookC / Java / Objective-Cclang-format.clang-format自动格式化Kotlindetekt.kotlinlint.yml基于 detekt 默认配置扩展SwiftSwiftLint.swiftlint.ymlswiftlint检查swiftlint autocorrect自动修复此外STYLE.md 还约定了一个跨平台共享枚举的做法由于没有直接的方式在各平台间通用共享一个枚举约定在库的**最低适用层core/bridge**定义枚举再通过extern const公开值向 bridge 与平台层共享保证跨语言取值的一致性。包容性语言策略Inclusive language policy所有 PR 的代码、API 与文档都必须遵守以下用词替换规则禁用词替换为whitelistallowlistblacklistdenylist 或 blocklistmasterprimaryslavesecondary 或 replica文档还要求整体采用包容性写作风格并说明该策略并非定论可能随行业最佳实践演进而修订维护者也可能在评审中针对此主题提出补充意见。三、提交 PR 的完整清单mobile/CONTRIBUTING.md 中的Submitting a PR一节给出了一条必须逐项满足的硬性清单Fork 仓库、创建 PRCI 会自动运行测试不合并任何测试未通过的 PR新增代码要求100% 测试覆盖率若无法达到必须在 PR 中明确解释原因任何改变用户可见行为的 PR 必须附带文档包括 mobile/docs 下的对应文档以及 mobile/docs/root/intro/version_history.rst 中的 release notes代码注释与文档要求正确的英文语法与标点PR 标题规范描述性标题一般以子系统名 冒号开头例如docs: fix grammar error、http conn man: add new featurePR 描述要说明做了什么若修复已有 issue需以Fixes #XXX结尾以便合并时自动关闭 issue提交后请勿 rebase后续补充应以新 commit 或 merge 形式追加最终合并时会做 squash rebasecommit 数量不影响评审开启后需持续活跃推进Stalebot 会在 14 天无活动后自动关闭 PR之后可再重新打开。规范中还留有一个 TODO为 prepush hook 提供 bootstrap 脚本对应社区 issue 中的待办项说明 pre-push 环节的自动化工具链仍在演进中。维护者评审政策通常争取在1 个工作日内完成评审期望由 PR 所涉代码的领域专家评审该人不一定是维护者仅更新文档/注释、或对测试与工具的琐碎改动由维护者判定可豁免此规则任何社区成员都可以主动评审任何 PR合并前必须清理标题与正文GitHub squash merge 默认会把 PR 内每个 commit 堆进 commit body合并的维护者应确保标题符合上述规范用 PR 的原始扩展描述覆写 body可适度整理并保留 PR 作者的 DCO sign-off。四、DCO 签名机制、原理与修复4.1 什么是 DCO sign-offDCO 要求在每个 git commit message 末尾追加一行证明你对补丁拥有合法的开源提交权Signed-off-by: Joe Smith joegmail.com必须使用真实姓名不接受匿名或化名。该认证声明对应 developercertificate.org 的开发者原创证书 1.1 版核心承诺包括四种情形之一(a) 代码由你创建且有权按开源许可证提交(b) 基于既有开源工作修改且有权提交(c) 由已做出上述认证的人直接提供且你未修改(d) 你理解贡献及附带个人信息将被永久公开记录。4.2 自动化方式bootstrap 脚本与 git hooks规范给出的自动化入口是先初始化子模块再在仓库根目录运行 bootstrap 脚本git submodule update --init --recursive ./envoy/support/bootstrap适用前提说明文档中写的路径./envoy/support/bootstrap对应独立的 envoy-mobile 仓库布局克隆目录名为envoy在本仓库的 monorepo 布局中该脚本实际位于 support/bootstrap。从源码看support/bootstrap 的工作流程是校验当前必须位于仓库根目录比对pwd -P与git rev-parse --show-toplevel通过git rev-parse --git-common-dir定位.git目录找不到时回退到--git-dir兼容 submodule 场景把support/hooks/下的两个钩子软链进.git/hooks/prepare-commit-msg与pre-push设置REINSTALL_HOOKS1环境变量可强制重装。其中 support/hooks/prepare-commit-msg 是 DCO 自动签名的核心实现它在git commit生成默认信息之后、打开编辑器之前介入先用git var GIT_AUTHOR_IDENT取出作者身份再检查 commit message 中是否已存在该Signed-off-by行若不存在则自动追加并向用户打印提示。这样忘记签名这一最常见的 DCO 失败原因在本地就被消除了。而 support/hooks/pre-push 则在推送前自动运行格式检查 DCO 签名检查任一失败都会阻止 push 成功。源码中还有两个值得注意的细节设置环境变量NO_VERIFY1或加入.env文件可跳过 pre-push 检查等价于git push --no-verify钩子内置了远端 SSH 空闲超时保护默认阈值PRE_PUSH_REMOTE_IDLE_WARNING_SECONDS300秒若本地检查耗时超过该阈值会打印警告提示 push 可能因远端连接空闲超时而中断需要重试。4.3 手动方式与 git alias如果不使用 hook可以在创建 commit 时直接用-s参数签名或配置 git 别名让签名成为默认行为git config --add alias.amend commit -s --amend git config --add alias.c commit -s配置后git c与git amend都会自动带上 sign-off。4.4 DCO 检查失败后如何修复若 PR 已经在远端且 DCO 检查失败需要修复 PR 的整段commit 历史。规范推荐的最佳实践是把历史 squash 成单个 commit追加 DCO 签名然后 force pushgit rebase -i HEAD^^ # (交互式 squash 追加 DCO 签名) git push origin -f规范特别强调改写历史一般会给评审过程带来干扰这一步仅应用于纠正 DCO 失误不要与提交后不要 rebase的常规要求混淆。4.5 CI 卡住时触发重跑kick-ci有时 CI 任务会卡住而不被标记为失败导致无法通过正常方式重跑。规范给出的解决方案是推送一个空 commit来触发所有 CI 任务重跑并建议在~/.gitconfig中加入别名[alias] kick-ci !git commit -s --allow-empty -m Kick CI git push之后只需执行git kick-ciPR 就会被重新送测。注意该别名中的commit -s同样保证了空 commit 也带有 DCO 签名不会引发新的 DCO 失败。五、小结一条可执行的贡献检查清单把 mobile/CONTRIBUTING.md 的规范浓缩为动手前的检查顺序改动超过 100 LOC不含测试或触及用户可见行为→ 先开 issue 沟通必要时补设计文档用pre-commit run --all-files以及各语言的 clang-format/detekt/SwiftLint过一遍格式检查新增代码 100% 覆盖涉及用户可见行为时同步更新 mobile/docs 文档与 mobile/docs/root/intro/version_history.rst标题写成子系统: 描述正文说明改动内容修复 issue 时以Fixes #XXX结尾确认仓库已执行过 bootstrap或手动签名让 support/hooks/prepare-commit-msg 在每个 commit 上自动追加Signed-off-bysupport/hooks/pre-push 在推送前兜底校验提交后不 rebase保持 PR 活跃14 天无活动会被 Stalebot 关闭DCO 失败才走 squash force pushCI 卡死用git kick-ci重跑。按这条链路操作你的 PR 在评审、DCO 与 CI 三个关卡上都能一次通过。【免费下载链接】envoyCloud-native high-performance edge/middle/service proxy项目地址: https://gitcode.com/GitHub_Trending/en/envoy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考