Matter SDKconnectedhomeip贡献指南从 Fork-and-Pull 工作流到合并治理的完整解读【免费下载链接】connectedhomeipMatter (formerly Project CHIP) creates more connections between more objects, simplifying development for manufacturers and increasing compatibility for consumers, guided by the Connectivity Standards Alliance.项目地址: https://gitcode.com/GitHub_Trending/co/connectedhomeipMatter SDKconnectedhomeip前身 Project CHIP是 Connectivity Standards Alliance 维护的开源智能家居统一协议实现支持 Linux、ESP32、nRF、Silabs、Android、Darwin 等数十个平台。本文以仓库根目录的 CONTRIBUTING.md 为核心系统讲解向该仓库提交代码的完整流程贡献者身份要求、Fork-and-Pull 分支工作流、Pull Request 质量标准、CI 与合并治理含 fast-track 机制并结合仓库内的评审指南、代码规范与 GitHub Actions 工作流进行源码级印证。读完本文你将掌握在 Matter SDK 上提 Bug、做功能、写测试、过评审直至合并的完整实战路径。一、贡献前的身份与法律前提在动手写代码之前Matter SDK 明确了两种贡献者身份的权责边界1. 开源社区贡献者Open Source Contributor任何外部开发者都可以通过以下方式参与在 Issue Tracker 中提交 Bug 与功能请求以 Pull Request 形式提交不影响 Matter 规范的 Bug 修复与功能增强例如为其他编程语言Java、JS 等增加 API 绑定、硬件平台移植、对既有功能的优化实现。成为贡献者需要满足三项要求同意 Code of Conduct行为准则同意 Apache 2.0 License 许可协议签署 Matter Working Group CLA贡献者许可协议。注意一旦提交 PR即代表你拥有将该贡献授权给 Connectivity Standards Alliance 及社区的权利并同意其按 Apache 2.0 协议分发。2. CSA Matter 工作组正式成员如果计划提交影响 Matter 规范的改动如协议层面的行为变更则需要加入 CSA Matter Working Group要求包括为 Connectivity Standards Alliance 的 Participant 及以上级别成员是 Matter Working Group 成员已签署 Alliance Matter Working Group CLA获得所在公司官方审批人companys official approver的批准。这一区分决定了你的 PR 属于实现层改动还是规范层改动规范相关的功能需要走工作组的正式提案流程而普通实现修复则直接走开源 PR 通道。二、Bug 上报如何写出高质量 IssueBug 的提交流程遵循 BUG_REPORT.md 的规范。其核心出发点是一个 Bug 报告需要告诉开发者什么至少覆盖四要素问题是什么What如何复现How to reproduce以便开发者亲自验证、定位引入时机bisect、确认是否已修复问题在什么环节出现At what point发生在什么环境What environment。高质量报告的具体要求标题必须清楚描述问题本身因为 Issue 列表默认只展示标题Bug 通常靠标题排序筛选日志应作为附件拖拽或从底栏添加而不是内联在 Issue 正文中避免正文过长复现步骤与环境要突出显示如果通过命令复现命令应放在代码块中。问题描述范例来自仓库文档(Core dump) seen—— 直观明确正常情况下不应出现 core dumpFailure trying to read attribute X in cluster Y which is marked MANDATORY in the spec—— 引用规范解释为什么该属性读取应成功Running certification test TC-A-B-C fails at step 3: ...—— 引用预定义测试用例说明预期通过却失败。环境信息的最低要求一个最小的环境描述可以是Failed to commission nrf board using chip-tool running on linux. Used build on SHA abcde...。进一步可补充构建参考点Tested on TE9、Tested on interop branch xyz问题面判断Thread devices fail, tested with qpg and efr32可帮助判断是否为通用 Thread 问题构建差异Tested with avahi-build and it passes/fails、Passes with darwin-framework-tool and repl but fails with chip-tool。这些细节能帮助开发者快速缩小问题范围从仓库的 bug 报告模板 可见Matter SDK 把可复现性视为 Bug 报告的第一优先级。三、新功能请求大功能先提案小功能直接 PR新增功能同样通过 Issue 发起但仓库根据功能规模给出了不同路径大型功能Large feature先提交 GitHub Issue 说明方案让社区提前评审反馈。早期反馈既能保证实现被社区接受也能协调各方工作、避免重复劳动小型功能Small feature可直接实现并以 PR 提交。这一策略与 pull_request_guidelines.md 中强烈偏好小 PR的原则一脉相承大改动需要设计文档、跨公司评审小改动则可以快速合入。四、Fork-and-Pull 工作流从克隆到提交的完整命令链Matter SDK 采用经典的Fork-and-Pull模型接受贡献。所有贡献必须通过全部检查与评审才能被接受。1. 初始环境搭建# Fork 仓库在 GitHub 网页端点击 Fork # 然后克隆你的 fork git clone gitgithub.com:username/connectedhomeip.git # 配置 upstream 别名指向官方仓库 git remote add upstream gitgithub.com:project-chip/connectedhomeip.git2. 为每个新功能创建工作分支# 基于 origin/master 创建跟踪分支 git branch --track branch-name origin/master # 检出分支 git checkout branch-name3. 创建提交# 添加需要提交的每个修改文件 git add file1 file2 # 创建提交会打开文本编辑器撰写提交信息 git commit4. 与上游同步与清理提交 PR 前建议将开发分支整理到最简状态便于维护者测试、接受与合并# 拉取上游 master 并与本地 master 合并 git checkout master git pull upstream master # 如果上游有新提交rebase 你的开发分支 git checkout branch-name git rebase master如果提交过于细碎可用交互式 rebase 将多个小提交压合成少量内聚的大提交git rebase -i master5. 推送并触发 CIgit checkout branch-name git push origin branch-name推送即触发持续集成检查结果可在对应 CI 服务中查看。注意集成检查偶尔会误报失败需要人工甄别。五、PR 质量标准让评审者高效工作的六项自检CONTRIBUTING.md 将详细规则指向 pull_request_guidelines.md。该指南开篇即给出 PR 提交前的短清单核心六项如下标题清晰可描述Descriptive/clear titlePR 规模可控单个改动只聚焦一个方面/缺陷/功能强烈偏好小 PR哪怕需要多个 PR 达成最终目标改动经过充分测试在 PR 摘要的### Testing小节说明测试方式含指令与命令强烈偏好自动化测试PR 摘要/描述质量高包含评审者所需的上下文、相关测试计划/规范变更链接改动核心/公共代码时说明 Flash/RAM 开销CI 通过绿色或黄色等待评审风格一致总原则是让代码感觉一致即修改文件时保持既有规则。5.1 标题规范描述性标题 vs 模糊标题平台特定改动应加前缀便于过滤测试改动可用[TC-ABC-1.2]之类标签。文档给出了两组对比好的标题示例[Silabs] Fix compile of SiWx917 if LED and BUTTON are disabled[Telink] Update build Dockerfile with new Zephyr SHA: c05c4.....General Commissioning Cluster: use AttributeAccessInterface/CommandHandlerInterface for processingFix crash during DNSSD processing due to malformed packet[TC-ABC-2.3] added new python test case based on test plan[TC-ABC] migrate tests from yaml to python模糊的标题示例应避免Work on issue 1234Fix android JniTypeWrappersFix segfault in BLEFix TC-ABC-1.2Update Readme5.2 PR 规模为什么必须小而专注小补丁更易评审也强制了代码解耦只有代码足够独立才可能做到小改动。但代价是合入前必须跑完整 CI全量运行通常需 2 小时以上。当前仓库明确优先保护评审者时间、偏好小补丁。规模统计只计被更新的代码不计测试文件测试通常比实现大、生成文件如zzz_generated目录、*.matter文件、darwin/kotlin/java/python 下的/generated/目录。可关联改动如代码、文档、测试一起但不得把无关改动混入同一 PR例如无关的文档错别字修复、一个 PR 修多个 issue。5.3 Testing 小节自动化测试优先单元测试一句added/updated unit tests即可感谢并接受这种简洁表述集成测试可简述为TC_*.yaml/py覆盖了该行为同时说明为何无法做单元测试手动测试必须包含详细信息运行了哪些 chip-tool 或 repl 命令、观察到的结果并解释为何无法自动化——这一要求故意繁琐以强力鼓励编写自动化测试。仅引用既有 PR/文档/计划说按 XYZ 测试过是不够的琐碎改动如修正Readme.md错别字仍需#### Testing小节可简写为N/A或checked new URL opens。但注意此类情况很少——例如修改 ID 中的错别字仍需说明如何验证新 ID 生效。此外PR 摘要中还应提供自动化覆盖率信息是否只覆盖了 happy path哪些边界情况未覆盖/无法覆盖仓库设定的自动化测试覆盖目标约为85%–90%。5.4 PR 摘要/描述给评审者足够上下文评审者通常比 PR 作者掌握更少上下文因此摘要应包含改动内容的TLDR改了什么、为什么若修复崩溃/错误说明根因若修复方式不直观解释为何采用该方案值得注意的信息特定平台问题、对棘手代码的补充说明、后续工作或 PR 依赖WHY避免只写 Fix compile error应附上报错示例与触发命令避免只用Fixes #1234引用 Issue仍应简述问题与修复评审上下文基于测试计划/规范 Issue 的改动附上依赖链接基于进行中工作常见于规范 Issue需明确说明大型改动应附设计文档链接改动公共代码时检查 RAM/FLASH 开销来源可使用 size tooling 收集数据技巧用Fixes #....语法在合并时自动关闭 Issue用#...引用相关 Issue相比只引用 Issue更推荐写一段简短说明帮助评审者少点几次链接。5.5 评审后的更新尽量用一个或少数几个提交回应评审意见且不要 squash 或 merge with master。因为 SDK 合并时会统一 squash历史会保持干净而你在 PR 中强推 squash 会让评审意见难以追溯。保留提交历史评审者才能对比不同版本差异、确认修改是否到位。六、文档与代码风格贡献的两类隐形门槛6.1 Doxygen 文档规范Matter 使用 Doxygen 标记或 markdown所有 C、C、Objective-C、Objective-C、Perl、Python 和 Java 代码详细规则见 Doxygen Best Practices, Conventions, and Style。6.2 代码风格与自动格式化代码风格以 Coding Style Guide 为准其第一条也是最重要的一条规则是When in Rome...入乡随俗对既有代码的扩展或修复应匹配原代码的主流风格切忌因个人偏好对代码大改特改。代码标准核心 SDK 采用C17与Python 3.11见 pyproject.toml 中requires-python 3.11及 ruff 配置的target-version py311。自动格式化工具矩阵如下全部 PR 在合并前都会跑格式化检查生成代码除外语言格式化工具风格文件Cclang-format.clang-formatObjective-Cclang-format.clang-formatJavagoogle-java-formatN/APythonpep8, isort, ruffpyproject.tomlYAMLprettier无JSONprettier无Markdownprettier无从仓库配置可验证.clang-format采用 WebKit 基础风格定制ColumnLimit: 132、基于 4 空格缩进pyproject.toml中 autopep8/isort/ruff 的行长统一为 132ruff 启用了包括E、W、F、ASYNC、COM、UP等在内的大量规则集并针对本仓库生成了排除清单如out/、third_party、生成文件等。6.3 面向嵌入式约束的编码要点该指南还强调了一组 Matter SDK 特有的嵌入式编码约束与贡献代码直接相关优先使用cstdint基础类型uint8_t、int8_t等尤其涉及大小、序列化到非易失存储或网络传输时头文件中避免顶层using namespace防止命名空间污染cpp 内部类/静态对象应置于匿名命名空间核心 SDK 公共代码避免堆内存分配与自动扩容的标准容器vector、string 等因为它们可能在嵌入式系统上导致内存耗尽与碎片化控制器代码允许堆分配平台特定代码由厂商酌情决定推荐替代方案就地分配与初始化、池化分配器、平台定义分配器实现见 src/lib/support/CHIPMem.h 与 src/lib/support/Pool.h使用 Span 时优先CopySpanToMutableSpan而非memcpy新代码优先使用std::optional替代 SDK 自带的 Optional 实现后者诞生于 C14 时代。6.4 文档的同等评审地位文档与代码经历同样的评审流程写作格式见 Documentation Style Guide。七、提交 PR 与合并要求7.1 提交动作CI 验证通过后进入 fork 页面选择开发分支点击 Pull Request 按钮提交。后续如需调整直接推送到 GitHubPR 会自动跟踪开发分支的变化。7.2 合并门槛Merge RequirementsGitHub Workflows 通过构建通过测试通过Lint 通过代码风格通过。上述全部满足后由评审者将 PR 合入 master。仓库根目录的 CODEOWNERS 展示了平台级代码的负责人矩阵例如darwin/与*.mm由project-chip/reviewers-apple负责esp32/由project-chip/reviewers-espressif负责*.java、*.kt与android/由project-chip/reviewers-google负责等——这意味着触碰特定平台代码时必须获得对应团队认可。八、合并治理三方评审、SDK Maintainers 与 fast-track8.1 标准合并流程合并至少需要 3 个来自不同 required-reviewers 名单的批准且全部 CI 通过。评审机制详见 pr_reviews.md按 GitHub 账号区分批准权重任何人可批准非project-chip组织成员的批准为灰色勾project-chip组织成员的批准为绿色勾但不天然增加权重reviewers-company组的成员批准通常计为公司批准独立的 matter-sdk-maintainers 组成员被明确授权合并达到质量标准的 PR。8.2 何时可以合并PR 必须满足 pull_request_guidelines.mdPR 必须先通过 CI 再被评审评审前应为绿色状态draft状态的 PR 可能不被评审合并阻塞项始终被尊重所有评论必须 resolveChanges requested状态必须由提出人解除后方可合并。8.3 附加规则平台与目录部分目录/平台有额外要求部分已自动化全部由评审者把关修改darwin需要 Apple 评审者reviewers-apple的批准/examples可有独立评审名单例如examples/chef由reviewers-google成员批准即可合并。8.4 SDK Maintainers 的职责SDK Maintainers 在 PR 达到质量门槛时被授权合并并明确验证指南与质量门槛是否满足确保评审覆盖充分维持高质量标准明确抵制时间压力不会为赶截止日期降低质量门槛优先质量而非作者便利历史上写出的代码多于可评审的带宽他们可能要求拆分、排序 PR 或补充测试可通过sdk-maintainer-approved标签将 PR 标记为可合并包括同公司作者的 PR大型架构改动、全新方案除外需多家公司评审。8.5 多公司评审与跨公司合并当前规则两个独立公司的代表批准且满足全部条件CI 通过、无未解决评论、无阻塞后PR 即被合并。8.6 快速合并机制Shorter Reviews / fast-trackCONTRIBUTING.md定义了面向开发负责人Development Lead与副负责人Vice Lead的快速路径以及单独的fast-track标签仅可由 Development Lead 设置如两人均不可用可临时委派替代者。注意Day 指工作日周五提交的 PR 不会因此更快被 fast-track。类型一琐碎改动Trivial changes——可立即 fast-track。典型示例增删文档.md文件新增测试含为可测试性做的小规模重构/方法调整认证测试、稳定性测试、集成测试、功能测试、测试脚本、遵循既有模式的新增测试如 YAML 测试新增/更新/修复开发辅助工具重新运行代码生成代码可读性重构重命名枚举/类/结构体成员、移动常量头文件位置、显然琐碎的构建规则改动如把缺失文件加入构建规则、修改注释、增删 include只包含所需头文件拉取第三方仓库文件平台厂商/维护者为自有平台新增功能、逻辑或 Bug 修复大多数对既有 Docker 文件的改动升级版本、重组工作流中新 Dockerfile 版本的大多数改动。类型二较大的功能改动Fast track changes——可 fast-track但有严格限制PR 创建后至少经过 1 个工作日至少 1 个熟悉相关代码或问题域的人给出认可该要求在 PR 满 3 天且无反馈/反馈过期后豁免代码被自动化测试充分覆盖或确实无法自动化测试且有充分理由例如 BLE 参数改动无法自动测试但应已手动验证。fast-track 时会 resolve 掉显然已处理的评论判断依据是否已回复或已处理然后合并改动。任何 request for changes 标记都会被尊重除非问题显然已解决即作者标记因 X 请求修改且 X 已在 PR 中完成该豁免同样在 PR 满 3 天后生效。8.7 新评审机制下的演进值得注意pr_reviews.md指出fast-track标签创建于matter-sdk-maintainers团队成立之前如今其使用预计非常少同时在某些情况下CI 损坏且短期内无法修复、紧急修复以解除他人阻塞、干净的回滚等管理员强制合并Admin Merges是被允许但应当罕见的操作。这说明该仓库的合并治理正处于从负责人特批向团队化质量把关演进的阶段。九、从 CI 工作流看质量护栏的实现CONTRIBUTING.md反复强调CI 通过是合并前提仓库 .github/workflows 下的大量 GitHub Actions 工作流正是这套护栏的具体实现可作为理解 CI 全貌的切入点跨平台构建矩阵examples-linux-arm.yaml、examples-esp32.yaml、examples-nrfconnect.yaml、examples-silabs-zephyr.yaml、examples-tizen.yaml等按平台拆分任何 PR 触碰对应平台都会被相关工作流验证质量与安全扫描codeql.yml静态安全分析、doxygen.yaml与docbuild.yaml文档构建校验、bloat_check.yaml代码体积检查与 PR 指南中改动公共代码需说明 Flash/RAM 开销的要求呼应测试与认证cirque.yaml集成测试、cert_test_checks.yaml、chef.yamlchef 示例设备测试流程管理cancel_workflows_for_pr.yaml、cherry-picks.yaml、issue-labeler.yaml、gradle-wrapper-validation.yml等保证 PR/Issue 生命周期有序。可见CI 通过并非单一检查而是覆盖构建、测试、lint、格式、体积、安全的组合闸门这也解释了为何一次全量 CI 运行耗时可达 2 小时以上——这是小 PR 减少无谓 merge with master策略的现实原因。十、贡献流程全景小结将全文串联起来Matter SDK 贡献者从零到合并的完整路径为法律准备同意 CODE_OF_CONDUCT.md、LICENSE、签署 CLA提出想法Bug 走 BUG_REPORT.md 四要素模板大功能先提 Issue 征求意见小功能直接动手Fork 与克隆Fork 官方仓库配置upstream远程别名建分支开发为每个功能建独立分支小步提交同步与整理git pull upstream mastergit rebase -i master压合提交推送过 CIgit push origin branch-name等待平台构建、lint、格式、体积等检查提交 PR按 pull_request_guidelines.md 六项清单撰写标题、摘要与### Testing小节目标测试覆盖率 85%–90%接受评审满足合并门槛Workflows/构建/测试/Lint/风格全通过达到 3 个不同 required-reviewers 批准或多公司评审要求由评审者或 SDK Maintainers 合并特殊通道琐碎改动与满足时限/测试条件的较大改动可由负责人通过fast-track加速。这套流程将质量优先落实为可操作的硬性机制小 PR 保证可评审性自动化测试保证可验证性多公司评审保证中立性而 fast-track 与 Admin Merges 等例外通道则保留了工程灵活性——理解这些机制是高效向 Matter SDK 贡献代码的前提。【免费下载链接】connectedhomeipMatter (formerly Project CHIP) creates more connections between more objects, simplifying development for manufacturers and increasing compatibility for consumers, guided by the Connectivity Standards Alliance.项目地址: https://gitcode.com/GitHub_Trending/co/connectedhomeip创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Matter SDK（connectedhomeip）贡献指南：从 Fork-and-Pull 工作流到合并治理的完整解读
Matter SDKconnectedhomeip贡献指南从 Fork-and-Pull 工作流到合并治理的完整解读【免费下载链接】connectedhomeipMatter (formerly Project CHIP) creates more connections between more objects, simplifying development for manufacturers and increasing compatibility for consumers, guided by the Connectivity Standards Alliance.项目地址: https://gitcode.com/GitHub_Trending/co/connectedhomeipMatter SDKconnectedhomeip前身 Project CHIP是 Connectivity Standards Alliance 维护的开源智能家居统一协议实现支持 Linux、ESP32、nRF、Silabs、Android、Darwin 等数十个平台。本文以仓库根目录的 CONTRIBUTING.md 为核心系统讲解向该仓库提交代码的完整流程贡献者身份要求、Fork-and-Pull 分支工作流、Pull Request 质量标准、CI 与合并治理含 fast-track 机制并结合仓库内的评审指南、代码规范与 GitHub Actions 工作流进行源码级印证。读完本文你将掌握在 Matter SDK 上提 Bug、做功能、写测试、过评审直至合并的完整实战路径。一、贡献前的身份与法律前提在动手写代码之前Matter SDK 明确了两种贡献者身份的权责边界1. 开源社区贡献者Open Source Contributor任何外部开发者都可以通过以下方式参与在 Issue Tracker 中提交 Bug 与功能请求以 Pull Request 形式提交不影响 Matter 规范的 Bug 修复与功能增强例如为其他编程语言Java、JS 等增加 API 绑定、硬件平台移植、对既有功能的优化实现。成为贡献者需要满足三项要求同意 Code of Conduct行为准则同意 Apache 2.0 License 许可协议签署 Matter Working Group CLA贡献者许可协议。注意一旦提交 PR即代表你拥有将该贡献授权给 Connectivity Standards Alliance 及社区的权利并同意其按 Apache 2.0 协议分发。2. CSA Matter 工作组正式成员如果计划提交影响 Matter 规范的改动如协议层面的行为变更则需要加入 CSA Matter Working Group要求包括为 Connectivity Standards Alliance 的 Participant 及以上级别成员是 Matter Working Group 成员已签署 Alliance Matter Working Group CLA获得所在公司官方审批人companys official approver的批准。这一区分决定了你的 PR 属于实现层改动还是规范层改动规范相关的功能需要走工作组的正式提案流程而普通实现修复则直接走开源 PR 通道。二、Bug 上报如何写出高质量 IssueBug 的提交流程遵循 BUG_REPORT.md 的规范。其核心出发点是一个 Bug 报告需要告诉开发者什么至少覆盖四要素问题是什么What如何复现How to reproduce以便开发者亲自验证、定位引入时机bisect、确认是否已修复问题在什么环节出现At what point发生在什么环境What environment。高质量报告的具体要求标题必须清楚描述问题本身因为 Issue 列表默认只展示标题Bug 通常靠标题排序筛选日志应作为附件拖拽或从底栏添加而不是内联在 Issue 正文中避免正文过长复现步骤与环境要突出显示如果通过命令复现命令应放在代码块中。问题描述范例来自仓库文档(Core dump) seen—— 直观明确正常情况下不应出现 core dumpFailure trying to read attribute X in cluster Y which is marked MANDATORY in the spec—— 引用规范解释为什么该属性读取应成功Running certification test TC-A-B-C fails at step 3: ...—— 引用预定义测试用例说明预期通过却失败。环境信息的最低要求一个最小的环境描述可以是Failed to commission nrf board using chip-tool running on linux. Used build on SHA abcde...。进一步可补充构建参考点Tested on TE9、Tested on interop branch xyz问题面判断Thread devices fail, tested with qpg and efr32可帮助判断是否为通用 Thread 问题构建差异Tested with avahi-build and it passes/fails、Passes with darwin-framework-tool and repl but fails with chip-tool。这些细节能帮助开发者快速缩小问题范围从仓库的 bug 报告模板 可见Matter SDK 把可复现性视为 Bug 报告的第一优先级。三、新功能请求大功能先提案小功能直接 PR新增功能同样通过 Issue 发起但仓库根据功能规模给出了不同路径大型功能Large feature先提交 GitHub Issue 说明方案让社区提前评审反馈。早期反馈既能保证实现被社区接受也能协调各方工作、避免重复劳动小型功能Small feature可直接实现并以 PR 提交。这一策略与 pull_request_guidelines.md 中强烈偏好小 PR的原则一脉相承大改动需要设计文档、跨公司评审小改动则可以快速合入。四、Fork-and-Pull 工作流从克隆到提交的完整命令链Matter SDK 采用经典的Fork-and-Pull模型接受贡献。所有贡献必须通过全部检查与评审才能被接受。1. 初始环境搭建# Fork 仓库在 GitHub 网页端点击 Fork # 然后克隆你的 fork git clone gitgithub.com:username/connectedhomeip.git # 配置 upstream 别名指向官方仓库 git remote add upstream gitgithub.com:project-chip/connectedhomeip.git2. 为每个新功能创建工作分支# 基于 origin/master 创建跟踪分支 git branch --track branch-name origin/master # 检出分支 git checkout branch-name3. 创建提交# 添加需要提交的每个修改文件 git add file1 file2 # 创建提交会打开文本编辑器撰写提交信息 git commit4. 与上游同步与清理提交 PR 前建议将开发分支整理到最简状态便于维护者测试、接受与合并# 拉取上游 master 并与本地 master 合并 git checkout master git pull upstream master # 如果上游有新提交rebase 你的开发分支 git checkout branch-name git rebase master如果提交过于细碎可用交互式 rebase 将多个小提交压合成少量内聚的大提交git rebase -i master5. 推送并触发 CIgit checkout branch-name git push origin branch-name推送即触发持续集成检查结果可在对应 CI 服务中查看。注意集成检查偶尔会误报失败需要人工甄别。五、PR 质量标准让评审者高效工作的六项自检CONTRIBUTING.md 将详细规则指向 pull_request_guidelines.md。该指南开篇即给出 PR 提交前的短清单核心六项如下标题清晰可描述Descriptive/clear titlePR 规模可控单个改动只聚焦一个方面/缺陷/功能强烈偏好小 PR哪怕需要多个 PR 达成最终目标改动经过充分测试在 PR 摘要的### Testing小节说明测试方式含指令与命令强烈偏好自动化测试PR 摘要/描述质量高包含评审者所需的上下文、相关测试计划/规范变更链接改动核心/公共代码时说明 Flash/RAM 开销CI 通过绿色或黄色等待评审风格一致总原则是让代码感觉一致即修改文件时保持既有规则。5.1 标题规范描述性标题 vs 模糊标题平台特定改动应加前缀便于过滤测试改动可用[TC-ABC-1.2]之类标签。文档给出了两组对比好的标题示例[Silabs] Fix compile of SiWx917 if LED and BUTTON are disabled[Telink] Update build Dockerfile with new Zephyr SHA: c05c4.....General Commissioning Cluster: use AttributeAccessInterface/CommandHandlerInterface for processingFix crash during DNSSD processing due to malformed packet[TC-ABC-2.3] added new python test case based on test plan[TC-ABC] migrate tests from yaml to python模糊的标题示例应避免Work on issue 1234Fix android JniTypeWrappersFix segfault in BLEFix TC-ABC-1.2Update Readme5.2 PR 规模为什么必须小而专注小补丁更易评审也强制了代码解耦只有代码足够独立才可能做到小改动。但代价是合入前必须跑完整 CI全量运行通常需 2 小时以上。当前仓库明确优先保护评审者时间、偏好小补丁。规模统计只计被更新的代码不计测试文件测试通常比实现大、生成文件如zzz_generated目录、*.matter文件、darwin/kotlin/java/python 下的/generated/目录。可关联改动如代码、文档、测试一起但不得把无关改动混入同一 PR例如无关的文档错别字修复、一个 PR 修多个 issue。5.3 Testing 小节自动化测试优先单元测试一句added/updated unit tests即可感谢并接受这种简洁表述集成测试可简述为TC_*.yaml/py覆盖了该行为同时说明为何无法做单元测试手动测试必须包含详细信息运行了哪些 chip-tool 或 repl 命令、观察到的结果并解释为何无法自动化——这一要求故意繁琐以强力鼓励编写自动化测试。仅引用既有 PR/文档/计划说按 XYZ 测试过是不够的琐碎改动如修正Readme.md错别字仍需#### Testing小节可简写为N/A或checked new URL opens。但注意此类情况很少——例如修改 ID 中的错别字仍需说明如何验证新 ID 生效。此外PR 摘要中还应提供自动化覆盖率信息是否只覆盖了 happy path哪些边界情况未覆盖/无法覆盖仓库设定的自动化测试覆盖目标约为85%–90%。5.4 PR 摘要/描述给评审者足够上下文评审者通常比 PR 作者掌握更少上下文因此摘要应包含改动内容的TLDR改了什么、为什么若修复崩溃/错误说明根因若修复方式不直观解释为何采用该方案值得注意的信息特定平台问题、对棘手代码的补充说明、后续工作或 PR 依赖WHY避免只写 Fix compile error应附上报错示例与触发命令避免只用Fixes #1234引用 Issue仍应简述问题与修复评审上下文基于测试计划/规范 Issue 的改动附上依赖链接基于进行中工作常见于规范 Issue需明确说明大型改动应附设计文档链接改动公共代码时检查 RAM/FLASH 开销来源可使用 size tooling 收集数据技巧用Fixes #....语法在合并时自动关闭 Issue用#...引用相关 Issue相比只引用 Issue更推荐写一段简短说明帮助评审者少点几次链接。5.5 评审后的更新尽量用一个或少数几个提交回应评审意见且不要 squash 或 merge with master。因为 SDK 合并时会统一 squash历史会保持干净而你在 PR 中强推 squash 会让评审意见难以追溯。保留提交历史评审者才能对比不同版本差异、确认修改是否到位。六、文档与代码风格贡献的两类隐形门槛6.1 Doxygen 文档规范Matter 使用 Doxygen 标记或 markdown所有 C、C、Objective-C、Objective-C、Perl、Python 和 Java 代码详细规则见 Doxygen Best Practices, Conventions, and Style。6.2 代码风格与自动格式化代码风格以 Coding Style Guide 为准其第一条也是最重要的一条规则是When in Rome...入乡随俗对既有代码的扩展或修复应匹配原代码的主流风格切忌因个人偏好对代码大改特改。代码标准核心 SDK 采用C17与Python 3.11见 pyproject.toml 中requires-python 3.11及 ruff 配置的target-version py311。自动格式化工具矩阵如下全部 PR 在合并前都会跑格式化检查生成代码除外语言格式化工具风格文件Cclang-format.clang-formatObjective-Cclang-format.clang-formatJavagoogle-java-formatN/APythonpep8, isort, ruffpyproject.tomlYAMLprettier无JSONprettier无Markdownprettier无从仓库配置可验证.clang-format采用 WebKit 基础风格定制ColumnLimit: 132、基于 4 空格缩进pyproject.toml中 autopep8/isort/ruff 的行长统一为 132ruff 启用了包括E、W、F、ASYNC、COM、UP等在内的大量规则集并针对本仓库生成了排除清单如out/、third_party、生成文件等。6.3 面向嵌入式约束的编码要点该指南还强调了一组 Matter SDK 特有的嵌入式编码约束与贡献代码直接相关优先使用cstdint基础类型uint8_t、int8_t等尤其涉及大小、序列化到非易失存储或网络传输时头文件中避免顶层using namespace防止命名空间污染cpp 内部类/静态对象应置于匿名命名空间核心 SDK 公共代码避免堆内存分配与自动扩容的标准容器vector、string 等因为它们可能在嵌入式系统上导致内存耗尽与碎片化控制器代码允许堆分配平台特定代码由厂商酌情决定推荐替代方案就地分配与初始化、池化分配器、平台定义分配器实现见 src/lib/support/CHIPMem.h 与 src/lib/support/Pool.h使用 Span 时优先CopySpanToMutableSpan而非memcpy新代码优先使用std::optional替代 SDK 自带的 Optional 实现后者诞生于 C14 时代。6.4 文档的同等评审地位文档与代码经历同样的评审流程写作格式见 Documentation Style Guide。七、提交 PR 与合并要求7.1 提交动作CI 验证通过后进入 fork 页面选择开发分支点击 Pull Request 按钮提交。后续如需调整直接推送到 GitHubPR 会自动跟踪开发分支的变化。7.2 合并门槛Merge RequirementsGitHub Workflows 通过构建通过测试通过Lint 通过代码风格通过。上述全部满足后由评审者将 PR 合入 master。仓库根目录的 CODEOWNERS 展示了平台级代码的负责人矩阵例如darwin/与*.mm由project-chip/reviewers-apple负责esp32/由project-chip/reviewers-espressif负责*.java、*.kt与android/由project-chip/reviewers-google负责等——这意味着触碰特定平台代码时必须获得对应团队认可。八、合并治理三方评审、SDK Maintainers 与 fast-track8.1 标准合并流程合并至少需要 3 个来自不同 required-reviewers 名单的批准且全部 CI 通过。评审机制详见 pr_reviews.md按 GitHub 账号区分批准权重任何人可批准非project-chip组织成员的批准为灰色勾project-chip组织成员的批准为绿色勾但不天然增加权重reviewers-company组的成员批准通常计为公司批准独立的 matter-sdk-maintainers 组成员被明确授权合并达到质量标准的 PR。8.2 何时可以合并PR 必须满足 pull_request_guidelines.mdPR 必须先通过 CI 再被评审评审前应为绿色状态draft状态的 PR 可能不被评审合并阻塞项始终被尊重所有评论必须 resolveChanges requested状态必须由提出人解除后方可合并。8.3 附加规则平台与目录部分目录/平台有额外要求部分已自动化全部由评审者把关修改darwin需要 Apple 评审者reviewers-apple的批准/examples可有独立评审名单例如examples/chef由reviewers-google成员批准即可合并。8.4 SDK Maintainers 的职责SDK Maintainers 在 PR 达到质量门槛时被授权合并并明确验证指南与质量门槛是否满足确保评审覆盖充分维持高质量标准明确抵制时间压力不会为赶截止日期降低质量门槛优先质量而非作者便利历史上写出的代码多于可评审的带宽他们可能要求拆分、排序 PR 或补充测试可通过sdk-maintainer-approved标签将 PR 标记为可合并包括同公司作者的 PR大型架构改动、全新方案除外需多家公司评审。8.5 多公司评审与跨公司合并当前规则两个独立公司的代表批准且满足全部条件CI 通过、无未解决评论、无阻塞后PR 即被合并。8.6 快速合并机制Shorter Reviews / fast-trackCONTRIBUTING.md定义了面向开发负责人Development Lead与副负责人Vice Lead的快速路径以及单独的fast-track标签仅可由 Development Lead 设置如两人均不可用可临时委派替代者。注意Day 指工作日周五提交的 PR 不会因此更快被 fast-track。类型一琐碎改动Trivial changes——可立即 fast-track。典型示例增删文档.md文件新增测试含为可测试性做的小规模重构/方法调整认证测试、稳定性测试、集成测试、功能测试、测试脚本、遵循既有模式的新增测试如 YAML 测试新增/更新/修复开发辅助工具重新运行代码生成代码可读性重构重命名枚举/类/结构体成员、移动常量头文件位置、显然琐碎的构建规则改动如把缺失文件加入构建规则、修改注释、增删 include只包含所需头文件拉取第三方仓库文件平台厂商/维护者为自有平台新增功能、逻辑或 Bug 修复大多数对既有 Docker 文件的改动升级版本、重组工作流中新 Dockerfile 版本的大多数改动。类型二较大的功能改动Fast track changes——可 fast-track但有严格限制PR 创建后至少经过 1 个工作日至少 1 个熟悉相关代码或问题域的人给出认可该要求在 PR 满 3 天且无反馈/反馈过期后豁免代码被自动化测试充分覆盖或确实无法自动化测试且有充分理由例如 BLE 参数改动无法自动测试但应已手动验证。fast-track 时会 resolve 掉显然已处理的评论判断依据是否已回复或已处理然后合并改动。任何 request for changes 标记都会被尊重除非问题显然已解决即作者标记因 X 请求修改且 X 已在 PR 中完成该豁免同样在 PR 满 3 天后生效。8.7 新评审机制下的演进值得注意pr_reviews.md指出fast-track标签创建于matter-sdk-maintainers团队成立之前如今其使用预计非常少同时在某些情况下CI 损坏且短期内无法修复、紧急修复以解除他人阻塞、干净的回滚等管理员强制合并Admin Merges是被允许但应当罕见的操作。这说明该仓库的合并治理正处于从负责人特批向团队化质量把关演进的阶段。九、从 CI 工作流看质量护栏的实现CONTRIBUTING.md反复强调CI 通过是合并前提仓库 .github/workflows 下的大量 GitHub Actions 工作流正是这套护栏的具体实现可作为理解 CI 全貌的切入点跨平台构建矩阵examples-linux-arm.yaml、examples-esp32.yaml、examples-nrfconnect.yaml、examples-silabs-zephyr.yaml、examples-tizen.yaml等按平台拆分任何 PR 触碰对应平台都会被相关工作流验证质量与安全扫描codeql.yml静态安全分析、doxygen.yaml与docbuild.yaml文档构建校验、bloat_check.yaml代码体积检查与 PR 指南中改动公共代码需说明 Flash/RAM 开销的要求呼应测试与认证cirque.yaml集成测试、cert_test_checks.yaml、chef.yamlchef 示例设备测试流程管理cancel_workflows_for_pr.yaml、cherry-picks.yaml、issue-labeler.yaml、gradle-wrapper-validation.yml等保证 PR/Issue 生命周期有序。可见CI 通过并非单一检查而是覆盖构建、测试、lint、格式、体积、安全的组合闸门这也解释了为何一次全量 CI 运行耗时可达 2 小时以上——这是小 PR 减少无谓 merge with master策略的现实原因。十、贡献流程全景小结将全文串联起来Matter SDK 贡献者从零到合并的完整路径为法律准备同意 CODE_OF_CONDUCT.md、LICENSE、签署 CLA提出想法Bug 走 BUG_REPORT.md 四要素模板大功能先提 Issue 征求意见小功能直接动手Fork 与克隆Fork 官方仓库配置upstream远程别名建分支开发为每个功能建独立分支小步提交同步与整理git pull upstream mastergit rebase -i master压合提交推送过 CIgit push origin branch-name等待平台构建、lint、格式、体积等检查提交 PR按 pull_request_guidelines.md 六项清单撰写标题、摘要与### Testing小节目标测试覆盖率 85%–90%接受评审满足合并门槛Workflows/构建/测试/Lint/风格全通过达到 3 个不同 required-reviewers 批准或多公司评审要求由评审者或 SDK Maintainers 合并特殊通道琐碎改动与满足时限/测试条件的较大改动可由负责人通过fast-track加速。这套流程将质量优先落实为可操作的硬性机制小 PR 保证可评审性自动化测试保证可验证性多公司评审保证中立性而 fast-track 与 Admin Merges 等例外通道则保留了工程灵活性——理解这些机制是高效向 Matter SDK 贡献代码的前提。【免费下载链接】connectedhomeipMatter (formerly Project CHIP) creates more connections between more objects, simplifying development for manufacturers and increasing compatibility for consumers, guided by the Connectivity Standards Alliance.项目地址: https://gitcode.com/GitHub_Trending/co/connectedhomeip创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考