Lynx 开源贡献实战指南从 Commit 规范、git lynx 检查到 CI Landing 全流程【免费下载链接】lynxEmpower the Web community and invite more to build across platforms.项目地址: https://gitcode.com/GitHub_Trending/lynx10/lynx本文基于 Lynx 仓库根目录的 CONTRIBUTING.md 整理成一篇可操作的贡献指南。读完本文你将掌握 Lynx 的完整贡献工作流Bug 报告与首次代码贡献的入口、强制性的 Commit Message 标签规范[Feature]/[BugFix]/Refactor等、git lynx check静态检查七项任务的逐项含义、git lynx format自动格式化以及 PR 评审、/land自托管 CI Landing 流程与 AI 辅助贡献的披露要求。一、贡献入口Bug 报告、增强建议与 First IssueCONTRIBUTING.md 将贡献路径分为四个层次从低门槛到高门槛依次是Reporting Bugs提交 Issue 时需包含清晰描述性的标题、可复现的步骤、以及有助于定位问题的附加信息或截图Suggesting Enhancements使用 Feature Request Issue 模板新建 Issue说明期望的增强及其实用价值Your First Code Contribution通过good first issue标签筛选新手友好问题先熟悉代码库再挑战复杂问题Pull Requests完成本地测试与验证后按下文规范提交 PR。这一分层设计降低了参与门槛不写代码也能通过高质量 Issue 参与项目而首次写代码的开发者可以从标签筛选出的简单问题入手。二、Pull Request 六步工作流文档给出的 PR 标准流程是Fork 仓库并 clone 到本地创建新分支git checkout -b name-of-your-branch完成代码修改在本地跑完必要测试后按下节格式提交 commit推送远程分支并发起 PR确保 PR 符合代码风格规范且文档完整。其中第 5 步有一条硬性约束值得特别注意原文强调We encourage the submission of small patches and only accept PRs that contain a single commit.即CI 会直接拒绝包含多于一个 commit 的 PR。如果你的改动涉及多个 commit要么拆分成多个 PR要么在不多的情况下 squash 成单个 commit。这一约束与 Chromium 系的 landing 模型一致目的是保证每次合入的最小可回滚单元就是一个 commit。2.1 Commit Message 格式核心规范CONTRIBUTING.md 定义了如下 commit 模板部分字段可选[Label] Title of the commit message (one line) Summary of change: Longer description of change addressing as appropriate: why the change is made, context if it is part of many changes, description of previous behavior and newly introduced differences, etc. Long lines should be wrapped to 72 columns for easier log message viewing in terminals. issue: #xxx doc: https://xxxxxxxx TEST: Test cases各字段的强制级别如下字段级别要求首行标题Required概括变更内容必须独占一行首个 LabelRequired必须是Feature、BugFix、Refactor、Optimize、Infra、Testing、Doc之一格式[Label]label 与标题之间必须有空格且标题不能为空摘要正文Required标题与正文之间必须空一行详述变更原因、上下文、行为差异issue: #xxxOptional关联 Issuedoc: https://xxxOptionalFeature/Refactor时必填关联设计文档TEST: test_case_1, test_case_2Optional列出单测/UI 测试用例名仓库中 agents/code_review/commit_message_format.md 进一步约定commit message 必须用英文书写首行推荐[Type][Scope] Short imperative summary形式其中 Scope 为模块或子系统名如Clay、Layout、Painting、Harmony、Android、iOS等可选但推荐。正文建议按改了什么 / 为什么需要 / 如何验证或影响面三点组织。七类 Label 的选用标准文档给出了每类 label 的定义与实例[Feature]新功能、新接口或对已有功能的变更。[Feature] Add new API for data binding[Feature] Add service for light sensors[Feature][Log] Support async event report[BugFix]功能缺陷、性能异常、开发者工具问题的修复。[BugFix] Fix exception when playing audio[BugFix] Fix leaks in xxx[BugFix][DevTool] Fix data error in DevTool[Refactor]模块或功能级的大规模代码重写/架构优化小规模重构应归入Optimize。[Refactor][Memory] Memory management in xxxx[Refactor][TestBench] XX module in TestBench[Optimize]小规模的性能/内存等指标优化。[Optimize][Performance] Jank when scrolling in xxxx[Infra]编译框架、CQ 配置、基础工具等。[Infra][Compile] Use -Oz compile params in xxx[Testing]测试用例与测试框架本身的修改。[Testing][Android] Fix xxx test case for Android[Testing] Optimize test process两条容易踩坑的归类规则原文特别强调仅涉及测试用例的改动即使是 BugFix 也应归为Testing若同一个 patch 同时提交Feature代码和相关测试用例则整体归为Feature。另外CI 工作流会校验 commit message 是否符合上述格式所以应在发起 PR 之前先保证格式正确——git lynx check中的commit-message任务就是干这件事的。2.2 AI 辅助贡献的披露义务CONTRIBUTING.md 专设 AI-Assisted Contributions 一节要点有四若 AI 工具对提交内容有实质性作用须在 PR 描述中披露并在 commit message 中添加 trailerAssisted-by: GitHub Copilot替换为实际工具名提交者对内容负全责必须能解释变更内容、正确性、与项目的契合点以及所做的测试评审中的提问应基于自身理解作答而非再去问一遍 AI无论手写还是 AI 辅助提交即表示拥有按项目 License 授权的权限需像审查任何陌生来源代码一样审查 AI 产出中的许可、版权、署名与安全问题Maintainer 按同一标准评审 AI 辅助贡献可能关闭测试不充分、提交者无法解释、或需要 maintainer 重写后才能评审的 PR。三、PR 验证与评审Default Reviewers 与一周评审窗口一个 PR 要合并必须通过 CI 工作流验证并获得 Lynx authors 的评审。文档给出的操作路径可以邀请仓库 contributor 评审不知道该找谁时从GitHub 分支保护规则和git blame入手评审列表中必须至少包含一位DEFAULT_REVIEWERS 文件中列出的默认评审人默认评审人能触发 CI 工作流运行以验证变更首次向 Lynx 提交 PR 的作者在 PR 提交后会看到 pending approval 提示随后启动 landing 流程通常 PR 在一周内完成评审CI 全部通过后landing 流程会被手动触发。仓库根目录的 DEFAULT_REVIEWERS 文件维护了默认评审人名单约近百名 contributors这是触发 CI 验证的关键权限载体。3.1 静态代码分析任务git lynx checkCI 任务包含静态代码分析、单元测试、构建等。本地可通过三步执行静态检查source tools/envsetup.sh tools/hab sync . -f git lynx check其中tools/hab sync . -f是 Lynx 依赖同步命令。从 tools/hab 启动脚本看hab是 Lynx 封装的 habitatPython 打包构建工具入口脚本内__version__0.3.149首次运行会把hab.pex下载到~/.habitat_cache/habitat/0.3.149/缓存目录若sync时返回 126版本不兼容会自动解析报错中的期望版本并重新下载安装。tools/envsetup.sh 则会 source tools/env.sh 完成环境初始化——后者定义了完整的工具链 PATHbuildtools下的llvm/bin、gn、ninja、sccache、emsdk、node/bin、ktlint等目录以及ANDROID_NDK21.1.6352462 等版本固定的 SDK 路径因此source tools/envsetup.sh后执行git lynx check前必须完成hab sync否则构建工具缺失。git lynx check会执行以下七项任务原文档表格完整保留Task NameDescriptioncoding-styleCheck the coding style of filescommit-messageCheck the format of commit messagecpplintCheck your C code for style violations and potential errorsjava-lintCheck your Java code for style violations and potential errorsandroid-check-styleCheck the import style of Android codefile-typeCheck whether there are any binary files (We do not recommend storing binary files in the repository)api-checkCheck changes to public APIs and update the corresponding API files as needed单项任务可独立执行例如git lynx check --checkersapi-checkcoding-style任务支持的语言与格式化工具对应关系原文档表格LanguageSupportedFormatting ToolC, C, Objective-C, Java支持clang-formatTypeScript支持prettierGN支持gn从仓库结构可印证这套工具链的覆盖面C 侧有根目录 CPPLINT.cfg 与 base/CPPLINT.cfg、clay/CPPLINT.cfg、clay/third_party/CPPLINT.cfg 等多级 cpplint 配置构建侧使用 GN仓库内含大量BUILD.gn如 BUILD.gn、core/BUILD.gnTypeScript 侧有 tsconfig.json、package.json 与 pnpm workspacepnpm-workspace.yamlapi-check对应的公开 API 文件可参见 platform/darwin 下的*.api文件等。四、Landing Pull Requests/land与自托管 CI为防止新变更破坏集成测试所有 PR 必须由自托管 CI 系统 landing。流程是PR 就绪后默认评审人在 PR 中评论/land命令CI 系统启动 landing 流程并跑全量测试耗时较长需耐心等待若 landing 过程中失败按情况分两种处理若破坏测试的变更本身是合理的默认评审人会在自托管代码库中修复并重启流程此时 PR 作者只需等待合并若测试发现变更存在 bug则启动 landing 的人负责向 PR 作者反馈问题与信息bug 修复后作者需重新走验证与评审流程再等待 reland所有检查通过后PR 自动合并。这套作者不能自己合并的模型保证了每次合入前在干净的自托管环境上完成了全量验证。五、Code StyleGoogle 风格指南与 git lynx formatLynx 遵循 Google 的编码风格指南C、Java、Objective-C、Python目标是保证代码一致、清晰、高质量。风格检查失败时仓库提供了自动格式化工具git lynx format注意其作用域限制它只检查已提交的变更committed changes未提交的本地修改不在检查范围内。因此推荐的顺序是先 commit再跑git lynx formatgit lynx check若有格式改动则 amend 进唯一 commit保持单 commit 约束。六、Testing让变更被测试覆盖CONTRIBUTING.md 要求尽可能确保变更被测试覆盖并链接到 testing/README_UT.md。该文档给出了各平台的实操细节C 单测基于 Google Test测试文件与源文件同目录且以unittests后缀命名如hello.cc对应hello_unittests.cc新测试文件需加入同目录BUILD.gn的unittest_set与unittest_exec目标并注册到 .rtf/native-ut-lynx.template该文件确实存在另有 config、android-ut-lynx.template 等模板然后执行tools/rtf/rtf native-ut run --names lynx --target hello_unittest_execRTFReusable Testing Framework是 Lynx 的测试管理框架见 tools/rtf/README.md支持模板化集中管理、多构建环境隔离、动态参数与并行执行Android 单测基于 JUnit4 instrumentation testing模拟器跑tools/rtf/rtf android-ut run --name lynx真机加--rmdiOS 单测基于 XCTest通过 LynxExplorer Xcode workspace 运行。在 commit message 的TEST:字段中填写这些用例名能把代码变更与验证用例显式关联起来这也是评审时的快速验证入口。七、Code of Conduct所有参与者须遵守 CODE_OF_CONDUCT.md参与即表示同意其条款。附贡献检查清单TL;DR发起 Lynx PR 前对照以下清单自查PR 只包含1 个 commit分支名清晰commit message 英文首行[Label] TitleLabel 取自七类之一标题与正文间空行正文 72 列折行Feature/Refactor类变更已附doc: https://...链接测试相关字段issue: #xxx、TEST: case1, case2已按需填写若使用 AI 辅助PR 描述已披露且 commit 含Assisted-by: tool nametrailer本地已执行source tools/envsetup.sh→tools/hab sync . -f→git lynx check七项全绿格式问题用git lynx format修复变更被 testing/README_UT.md 所述对应平台的测试覆盖已邀请 DEFAULT_REVIEWERS 中的默认评审人等待其触发 CI 与/land。以上流程即 CONTRIBUTING.md 的完整落地路径本地规范先行commit 格式 静态检查 测试覆盖远端把关单 commit 约束 默认评审人 自托管 CI 全量 landing两套机制共同保证了合入代码的一致性与可追溯性。【免费下载链接】lynxEmpower the Web community and invite more to build across platforms.项目地址: https://gitcode.com/GitHub_Trending/lynx10/lynx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考