EarlGrey 贡献指南：从 CLA 签署到合并的完整协作流程解析

• 测试

EarlGrey 是 Google 开源的 iOS UI 自动化测试框架，本指南以仓库根目录的 CONTRIBUTING.md 为核心，系统讲解外部开发者参与 EarlGrey 开发所需经历的完整流程：从签署贡献者许可协议（CLA）、遵循代码评审规范、满足单元/功能测试门槛，到正确提交 GitHub Issue 与维护文档。读者读完本文后，将能按照官方规范准备可合并的 Pull Request，理解仓库内置 CI（Scripts/travis.sh）的检查机制，并掌握新 API 通过 Demo/EarlGreyContribs 项目孵化后再进入主框架的协作路径。

贡献前的准备工作

签署 Google 个体贡献者许可协议（CLA）

在 EarlGrey 仓库可以正式采用你的代码之前，必须先签署 Google Individual Contributor License Agreement（个体贡献者 CLA），该协议可在线完成。签署 CLA 的必要性在于：

• 你对你的改动拥有版权，即使改动成为 EarlGrey 代码库的一部分，这一版权仍然归属你；
• Google 需要获得你的许可才能使用和分发这些代码；
• Google 还需要确认你不会在明知代码侵犯他人专利权的情况下提交改动。

签署时机遵循"先评审、后签署"的节奏：你无需在提交代码评审之前就签署 CLA，但必须在代码被合入代码库之前完成签署。也就是说，提交 Pull Request 后，等成员批准了再补签即可。

对于较大的贡献，官方建议先通过 Issue 跟踪器与团队沟通想法，让维护者提前介入并给予指导。提前协调能有效避免后期返工带来的挫败感。

企业贡献者的不同协议

需要注意，公司或组织（corporation）做出的贡献适用与上述不同的协议：Google Software Grant and Corporate Contributor License Agreement（软件授权与企业贡献者许可协议），这一点在 CONTRIBUTING.md 末尾的 "The small print" 小节中明确说明。企业贡献者在提交代码前应确认采用哪一份协议。

代码评审（Code Review）流程

EarlGrey 规定：所有提交，包括项目成员自己的提交，都必须经过评审。仓库使用 GitHub Pull Request 作为评审载体。提交的代码需要遵守下面的规则清单。

Do's：应当遵循的规范

1. 保持 Pull Request 聚焦：一个 PR 只处理一个 Issue 或一个功能点。如果一次改动修复了多个独立问题，优先拆分为多个 commit，每个 commit 对应一个 Issue。

2. PR 必须关联 GitHub Issue：除纯粹的拼写/格式修正（trivial spelling/formatting fixes）外，每个 Pull Request 都必须先有一个对应的 Issue。没有对应 Issue 的 PR，请先创建 Issue 并与社区讨论，以确认该问题的影响程度。这样团队才能确定优先级，把精力集中在最紧迫的问题上；缺少变更背景上下文的 PR，无法保证能获得及时的评审和合并。

3. 提交前先跑通测试：在提交任何代码改动之前，必须确保 Tests/UnitTests 和 Tests/FunctionalTests 两个测试工程能够构建且全部测试通过。如果认为测试失败是框架本身的 bug，请到 Issue 跟踪器提交 Issue。

4. 等待 CI 验证：PR 通过人工初步评审后，Travis 会运行全部单元测试与功能测试；团队还会触发一次内部测试以检查是否引入进一步的破坏。每个阶段都会在 PR 上设置相应的标签（labels），一旦有测试被破坏，维护者会通知你。

5. 纯代码外改动可跳过 CI：如果 PR 不涉及任何代码改动（例如只改文档），可以在 git commit message 中加入[[ci skip]]来跳过 Travis 持续集成检查，避免给 CI 增加不必要的负担。

6. 实验性 PR 不会被合并：任何被标记为 experiment 的 PR（在标题中注明，或打上experiment标签）都不会被合并。它的作用是分享一个原型，从而从核心团队获取更多反馈。

7. 新 API 先进 EarlGreyContribs 孵化：如果提议给 EarlGrey 新增自定义 API，且该 API 仍处于实验阶段，请把它加入 Demo/EarlGreyContribs 工程进行验证。同理，任何新增的示例代码也必须先在 EarlGreyContribs 工程中验证。从仓库的工程结构看，EarlGreyContribs 包含EarlGreyContribs（Objective-C）与EarlGreyContribsSwift（Swift）两套界面代码，并配有 EarlGreyContribsTests 和 EarlGreyContribsSwiftTests 两个测试 target，二者均纳入持续集成。其 README 明确说明：如果你向其中一个 target 添加了 API，请在另一个 target 中同样复制一份（"If you add an API to either one of the targets, please replicate it in the other as well."），以保证 ObjC 与 Swift 两条路径都被验证。

8. 遵循 Google 代码风格：代码约定请参照 Google Objective-C style guide 与 Google Swift style guide；评论和 Issue 的格式请使用 GitHub 的 Markdown 格式规范。

Don'ts：应当避免的行为

• 不要随意刷 LGTM / +1：除非被明确要求，否则不要添加 LGTM 或 +1，它们只会增加对话噪音。
• 避免过度细碎的 PR：对于可以很容易合并成一次的改动，不要拆成多个小而碎的 Pull Request。
• 不要提交描述含糊的 PR：模糊的描述会拉长评审时间，因为评审者需要先分析代码到底做了什么；更详尽的描述能帮助评审者理解评审对象。
• 不要提交大而空的重构：拒绝提交"大规模重构/功能变更 + 模糊或极简描述 + 没有关联 Issue"的 Pull Request。

CI 的落地实现：travis.sh 背后的检查矩阵

上面提到的 Travis 检查并非空谈，仓库中的 Scripts/travis.sh 完整实现了这套 CI 逻辑。脚本以TYPE环境变量驱动，可以推断出其覆盖以下矩阵：

其中execute_xcodebuild函数有几个值得注意的实现细节（Scripts/travis.sh）：

• 测试命令在失败时最多重试 3 次：当xcodebuild以退出码 65 退出（测试未启动失败），且日志中没有出现 "Test Suite" 关键字时，才会重试——这是针对"测试尚未真正启动"场景的容错，脚本注释中也自嘲这是脆弱的检查，可能在未来 Xcode 版本中失效；
• 输出通过xcpretty -sc格式化并同时写入xcodebuild.log，便于失败分析；
• 除了检查xcodebuild退出码，还会用正则.*[1-9]\d* unexpected扫描日志，因为当测试的+setUp/+tearDown失败时 Xcode 不会返回错误码，只会把 "unexpected failure" 写进日志，需要额外兜底检查。

这意味着贡献者提交 PR 时，改动会同时被跑在单元测试、功能测试（ObjC/Swift）、Contribs 孵化测试和示例工程集成测试等多条 CI 流水线上，任何一条失败都会阻塞合并。

本地开发与测试环境准备

在本地复现 CI 环境、跑通单元测试与功能测试，需要先准备 EarlGrey 的三方依赖。仓库提供了一键脚本 Scripts/setup-earlgrey.sh，它会自动下载并安置三份依赖：

• fishhook（版本固定为 0.2）：facebook 的 C 函数钩子库，用于 EarlGrey 运行时对系统调用的拦截，下载后放在仓库根目录fishhook/；
• OCHamcrest（版本固定为 OCHamcrest-5.0.0）：iOS 的 Hamcrest 匹配器实现，是 EarlGrey 匹配器体系的基础；下载后需要执行 Scripts/rename-ochamcrestIOS.py 去掉 "IOS" 命名，最终形成EarlGrey/OCHamcrest.framework；
• OCMock（master 分支）：Objective-C mock 框架，供单元测试使用，下载后放在 Tests/UnitTests/ocmock 目录。

脚本设计为幂等：如果对应目录已存在则跳过下载并给出提示；若后续运行 EarlGrey 出现问题，官方建议删除这些目录后重新运行脚本。对应地，Demo/EarlGreyContribs/README.md 的 "Getting Started" 也推荐先运行 setup 脚本，再打开已预配置好测试 target 的EarlGreyContribs.xcodeproj。

GitHub Issues 规范

Do's：高质量 Issue 的标准

• 先充分检索文档：在提交 Issue 之前，务必先广泛检索现有文档（包括 docs 目录下的 api.md、features.md、faq.md 等）；作为开发者，请提供你自己都愿意阅读的 Issue 描述。
• 尽量详细：在评论和描述中尽可能详细。每个 Issue 都要附上：项目类型、使用的语言、Xcode 版本、错误堆栈（error trace）等。团队不希望为每个 Issue 都反复追问调试信息。
• 深度讨论走邮件组：深入的讨论请使用 EarlGrey Google Group，而不是开一个新的 GitHub Issue。
• API 变更必须同步文档：一旦发生 API 更新，请确保改动被记录在 docs/cheatsheet/cheatsheet.html 中。而 cheatsheet 的 PDF 和 PNG 版本（cheatsheet.pdf、cheatsheet.png）只在发布新的 EarlGrey CocoaPod 时更新——从仓库 Scripts/package.sh 可以看到，发布打包流程会把README.md、CHANGELOG.md、LICENSE和构建出的EarlGrey.framework一起打进 EarlGrey.zip，作为 GitHub Release 与 CocoaPod 部署的产物，这与"PDF/PNG 随 CocoaPod 更新"的约定是相互印证的。

Don'ts：会被直接关闭的 Issue

• 含糊其辞的 Issue 会立即被关闭（"Any vaguely worded issue will be immediately closed"）；
• 长期无活动的 Issue 会被关闭：如果某个 Issue 长时间没有动静，它会被关闭；若问题仍然存在，请更新该 Issue 并重新打开。

变更日志与版本配套约定

虽然 CONTRIBUTING.md 没有逐字展开，但从仓库配套文件可以推断出与贡献流程直接相关的配套约束：

• CHANGELOG.md 记录了每个版本的变更，采用语义化版本（semantic versioning），且每个版本条目会给出 Baseline commit 与 Enhancement/Bug Fixes/Compatibility 分类。贡献者提交用户可见的改动时，合理的做法是同时在 CHANGELOG 中留下对应条目。
• 版本配套的兼容性声明（如 "tested for working till Xcode version 10.1 and Swift 5"）都写在 CHANGELOG 的 Compatibility 小节中，贡献者应避免引入超出声明范围的依赖。

与贡献流程相关的框架内联约束

最后，从源码层面补充一个与"提交前检查"呼应的细节：EarlGrey 在运行时有一系列可配置项（EarlGrey/Common/GREYConfiguration.m），其中kGREYConfigKeyAnalyticsEnabled默认值为@YES——即默认启用匿名使用统计（GREYAnalytics.m 在GREY_CONFIG_BOOL(kGREYConfigKeyAnalyticsEnabled)为真时才上报）。这对贡献者意味着：跑测试时产生的统计请求属于框架预期行为；而在 Tests/FunctionalTests/Sources 中还有一组FTRAnalytics*Test.m专门验证分析开关、tearDown 后的退出（opt-out）行为。贡献者在编写或修改涉及配置默认值的代码时，应保证这类行为测试仍然通过。

小结：一次完整的 EarlGrey 贡献旅程

综合以上规范，一个标准的贡献流程可以概括为：

1. 沟通：通过 Issue 跟踪器说明想法，与社区确认影响范围与优先级；
2. 准备：本地运行 Scripts/setup-earlgrey.sh 装好 fishhook、OCHamcrest、OCMock 三份依赖；
3. 开发：遵循 Google ObjC/Swift 代码风格，保持 PR 聚焦单一 Issue；新 API 先放进 Demo/EarlGreyContribs（ObjC 与 Swift 双 target 都要覆盖）孵化验证；
4. 自测：确保 Tests/UnitTests 与 Tests/FunctionalTests 构建通过、测试全绿；涉及 API 变更时同步更新 docs/cheatsheet/cheatsheet.html；
5. 提交：创建关联 Issue 的 Pull Request，接受 Travis 全矩阵检查（单元/功能/Contribs/示例集成），必要时用[[ci skip]]跳过纯文档改动的构建；
6. 签署：在代码合入前完成 Google 个体 CLA（企业贡献者则走企业 CLA）；
7. 合并：通过人工评审与 CI 后合入，非代码改动会触发内部测试复检。

这条流程既保证了 EarlGrey 这一被广泛依赖的测试框架的质量底线，也让外部贡献者的工作有章可循、可预期。

• 测试