Flipper Zero 固件仓库中的 Mbed TLS 贡献指南从 PR 提交到 LTS 分支的全流程解析【免费下载链接】flipperzero-firmwareFlipper Zero firmware source code项目地址: https://gitcode.com/GitHub_Trending/fl/flipperzero-firmware本篇文章以 Flipper Zero 固件仓库内集成的 Mbed TLS位于 lib/mbedtls官方贡献指南为骨架系统讲解向该开源密码库提交补丁的完整流程从贡献前的快速检查清单、编码标准、PR 提交流程到向后兼容性约束、LTS 分支回移植规则、测试套件编写、CI 与 git hooks、ChangeLog 要求以及双许可与 DCO 签署规则。读完本文你将掌握一套可直接套用的开源贡献方法论并能结合仓库源码理解 Mbed TLS 在 Flipper Zero 中的实际裁剪与集成方式。贡献前快速检查清单Mbed TLS 项目欢迎社区提交 bug 报告与代码贡献所有 Pull Request 都会经过项目团队与社区评审且可能要求多次修改后才能被合并。在动手之前请对照官方 CONTRIBUTING.md 给出的四条快速检查项Sign-off所有提交commit必须包含Signed-off-by:签名行用于确认代码符合开发者原创证书DCO要求TestsPR 必须包含足以证明功能正确性或 bug 已修复的测试Changelog如涉及用户可见变更需要提供对应的 ChangeLog 条目Backports若缺陷同样存在于 LTS 分支需要提供回移植补丁可等主 PR 合并后再补这是允许的。这四项对应了后续章节的详细规则建议作为提交前的自查清单逐条核对。编码标准与贡献的通用要求官方指南对贡献代码提出了四条基本要求必须携带测试详见测试与持续集成测试两节。提交前先通过基础测试提交 PR 后再关注 CI 结果风格干净可读代码必须遵循 Mbed TLS 的编码标准clean and readable style可移植、面向全社区代码应以通用可移植的方式编写使整个社区受益而不是只满足个人需求安全性优先所有代码都会从安全角度被评审。这四条标准意味着贡献者在编写代码时就要同时考虑正确性、可移植性与安全性评审阶段也会围绕这三个维度展开。贡献流程五步法官方指南给出的提交流程分为五个步骤先讨论后动手查看已存在的 issue或围绕功能想法/bug 发起讨论避免重复劳动Fork 仓库并选择正确基线通常应以development分支为基底进行修改先写测试编写一个能证明 bug 已修复或功能符合预期的测试——测试先行是 Mbed TLS 一贯的开发模式提交 PR 并跟进评审与维护者协作直到合并发布。贡献可能需要多轮修改评审过程中一次或数轮 review 与修正都是正常现象控制 PR 规模为加快合并速度贡献应尽量短小、聚焦于单一功能或主题。贡献越大评审与合并所需时间越长。从仓库结构看这一流程与 Mbed TLS 自身的分支模型见 BRANCHES.md深度绑定development分支是下一个大版本4.0的孵化地因此以 development 为基底是保证改动最终进入主线的前提。向后兼容性API 变更的严格约束向后兼容是 Mbed TLS 的核心工程原则。项目力求用户升级到更新版本时无需修改任何自身代码除非用户主动选择使用新特性、切换到新世代库版本或变更因安全缺陷等原因确有必要。为达成这一目标官方制定了以下规则主开发分支与 LTS 分支均维持 API 兼容性详见 BRANCHES.md即使是在新增功能的主开发分支上任何 ABI/API 变更都必须有充分理由——或是显著增强、新功能或是必须通过接口变更才能解决的 bug禁止修改公共接口中函数的定义。接口只能通过扩展来演进需要变更的现有函数先标记为deprecated弃用若确需用新函数替代旧函数原型或文档化行为不同则创建一个具有新名称、新接口的函数旧函数保留并标记为弃用弃用函数会按计划、结构化地分批移除移除属于破坏性 API 变更必须给用户足够的预告期。从 BRANCHES.md 可看到更细的约定仓库采用语义化版本Semantic Versioningmain分支在次要版本间保持 API 兼容只有主版本号变更如 3.x → 4.0才会破坏 API。以下变更不视为兼容性破坏结构体/联合体中新增或重排字段、从结构中移除未文档化为公共的字段、枚举新增条目、函数返回了此前未文档化的新错误码、在多种错误条件并存时更换返回的错误码等。当安全与向后兼容冲突时安全优先但会尽量提供兼容选项。LTS 长期支持分支与回移植规则Mbed TLS 维护多个 LTS 分支在给定周期内持续维护。LTS 分支只接收安全修复与缺陷修复不引入可能改变代码体积或 RAM 占用的新特性/API 扩展——这对资源受限平台尤为重要。回移植到 LTS 分支必须遵守三条规则任何改变 API/ABI 的改动都不得回移植所有同时存在于 LTS 分支的缺陷修复都必须回移植。若某修复引入新函数等 API 变化应改写修复方案以避开 API 变更缺乏充分理由的 API 变更很难被接受新特性或增强不需要回移植例外是额外的测试用例或构建/测试脚本改进等质量提升。项目高度期望贡献者在提交development分支的同时主动将修复回移植到 LTS 分支。当前维护中的分支清单见 BRANCHES.md 的 Current Branches 一节其中明确列出了main、development、mbedtls-2.28与mbedtls-3.6等分支及其维护截止时间。测试要求function 文件与 data 文件的结构测试是 Mbed TLS 贡献的核心门槛——PR 必须包含证明功能正确性或 bug 已修复的测试若尚不存在此类测试。Mbed TLS 在 tests/ 目录下维护了一套全面的测试套件其组织方式是本项目测试体系的关键测试套件是动态生成的实际测试源文件如test_suite_rsa.c由一对模板文件生成function 文件如suites/test_suite_rsa.function包含测试函数定义data 文件如suites/test_suite_rsa.data包含测试用例以参数形式传递给测试函数。以仓库中实际存在的 tests/suites/test_suite_aes.ecb.data 为例其典型的用例格式为AES-128-ECB Encrypt NIST KAT #1 aes_encrypt_ecb:00000000000000000000000000000000:f34481ec3cc627bacd5dc3fb08f273e6:0336763e966d92595a567cc9ce537f5e:0每两条记录构成一个用例首行为用例名称次行为测试函数名 冒号分隔的参数本例中依次为密钥、明文、期望密文、预期返回码。这种function data分离的设计使得新增测试只需补充函数与数据而不必改动测试主框架。此外还有以下配套要求脚本 tests/scripts/basic-build-test.sh 可用于展示库的测试覆盖率新代码贡献应提供与库中既有代码相近的覆盖率水平如涉及示例程序应同步修改。持续集成测试与 git hooksPR 提交后会自动触发持续集成CI测试。贡献者需要跟进 CI 结果并修复失败项。官方建议在推送改动前启用 git hooks 脚本尽早捕捉问题。仓库中对应的脚本位于 tests/git-scripts其说明文档 README.md 给出了启用方法Git hooks 位于Mbed TLS root/.git/hooks不属于版本控制Mbed TLS 的 hooks 位于Mbed TLS root/tests/git-scripts需在.git/hooks中创建指向它的软链接例如在 Linux 上执行ln -s ../../tests/git-scripts/pre-push.sh pre-push注意当前 Mbed TLS 的 git hooks 仅支持 GNU 平台非 GNU 平台请勿启用这些脚本也可以独立运行。仓库中已提供pre-push.sh脚本即推送前自动执行检查的钩子。文档与 ChangeLog 要求Mbed TLS 文档体系完善官方指南要求贡献者在文档方面做到所有接口必须通过 Doxygen 记录新 API 必须引入 Doxygen 文档代码中复杂部分应包含注释必要时建议添加 Readme 文件若需要新增 Knowledge Base 文章应在 PR 描述中注明必须为贡献添加 ChangeLog 条目。ChangeLog 的完整规范见 ChangeLog.d/00README.md要点如下ChangeLog.d/目录存放尚未合并进主 ChangeLog 的待定条目需要条目的是用户可见变更库或示例程序中的 bug 修复含安全漏洞修复、行为修复、特定配置/平台构建修复、新特性/新示例程序/新平台支持、既有行为变更等一般不需要条目的是文档改进、性能改进除非特别显著、用户不直接交互的内部代码变更如测试代码与测试数据、普通编译器警告修复条目文件必须以*.txt结尾采用分类格式合法的分类为API changes、Default behavior changes、Requirement changes、New deprecations、Removals、Features、Security、Bugfix、Changes其余归入Changes格式细节每条条目以三个空格 星号 空格开头续行以 5 个空格开头行宽不超过 79 字符使用现在时与祈使句例如 Fix a bug in mbedtls_xxx() …涉及 issue 时使用#1234格式涉及 CVE 等外部引用也一并标注写作原则是Explain why, not how——面向库的使用者而非开发者bug 修复要说明 bug 的后果而非修复方法新特性要说明价值API 变更/弃用要说明如何迁移既有应用主 ChangeLog 的更新通过运行scripts/assemble_changelog.py将ChangeLog.d中的条目合并进主文件。许可、版权与 DCO 签署Mbed TLS 采用双许可模式这是贡献者必须理解的法律基础除文件中特别注明外Mbed TLS 文件以Apache-2.0 OR GPL-2.0-or-later双许可发布完整文本见 LICENSE用户可任选其一使用贡献者必须接受其贡献同时基于Apache-2.0 AND GPL-2.0-or-later两个许可证提交所有新文件应尽量包含标准 SPDX 许可证标识SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later版权归原作者保留新文件尽量在文件头部注释中注明Copyright The Mbed TLS Contributors提交代码时提交者与所有作者必须依据 dco.txtDeveloper Certificate of Origin开发者原创证书提交确认代码可以合法地成为项目的一部分并同时按 Apache-2.0 与 GPL-2.0-or-later 提交。DCO 的具体落实方式是在每条 commit message 中包含标准 Git 签名行Signed-off-by:若一个提交有多个贡献者每位贡献者都应添加自己的Signed-off-by:行。结合仓库源码Mbed TLS 在 Flipper Zero 中的集成作为补充观察 Flipper Zero 固件仓库是如何使用这个库的有助于理解贡献规则的现实背景。Flipper Zero 并未全量编译 Mbed TLS而是通过 lib/mbedtls.scons 做了按需裁剪构建脚本明确注释了 If we were to build full mbedtls, we would need to use this然后只选取aes.c、bignum.c、ecdsa.c、ecp.c、md.c、sha1.c、sha256.c、des.c等少量源文件参与编译。这正是 LTS 分支避免代码体积与 RAM 占用变化这一理念在嵌入式场景下的体现。配套的 mbedtls_cfg.h 是裁剪后的配置头文件通过MBEDTLS_CONFIG_FILE宏注入注释明确说明它只包含与 Flipper Zero 固件和应用相关的 Mbed TLS 配置子集需要更多特性时可以在应用中通过fap_private_libs引入完整 mbedtls或向仓库提 issue 请求加入默认配置。这种子集配置 按需扩展的用法正是 Mbed TLS 强调通过配置选项裁剪功能、且特性间互不影响enabling or disabling a cryptographic algorithm does not break code that does not use that algorithm的实践注脚。对贡献者而言这意味着当你在development分支新增算法或 API 时下游嵌入式集成方如 Flipper Zero是否启用该特性完全由各自的配置头文件决定——这正是官方向后兼容 配置化裁剪设计的价值所在。结语Mbed TLS 的贡献流程可以概括为一句话测试先行、风格可读、接口只扩不改、变更必须入档、提交必须签注。对照 CONTRIBUTING.md 的快速检查清单结合 BRANCHES.md 的分支策略、ChangeLog.d/00README.md 的条目规范与 tests/ 的套件结构任何贡献者都能以最小的返工成本提交出高质量 PR。【免费下载链接】flipperzero-firmwareFlipper Zero firmware source code项目地址: https://gitcode.com/GitHub_Trending/fl/flipperzero-firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Flipper Zero 固件仓库中的 Mbed TLS 贡献指南：从 PR 提交到 LTS 分支的全流程解析
Flipper Zero 固件仓库中的 Mbed TLS 贡献指南从 PR 提交到 LTS 分支的全流程解析【免费下载链接】flipperzero-firmwareFlipper Zero firmware source code项目地址: https://gitcode.com/GitHub_Trending/fl/flipperzero-firmware本篇文章以 Flipper Zero 固件仓库内集成的 Mbed TLS位于 lib/mbedtls官方贡献指南为骨架系统讲解向该开源密码库提交补丁的完整流程从贡献前的快速检查清单、编码标准、PR 提交流程到向后兼容性约束、LTS 分支回移植规则、测试套件编写、CI 与 git hooks、ChangeLog 要求以及双许可与 DCO 签署规则。读完本文你将掌握一套可直接套用的开源贡献方法论并能结合仓库源码理解 Mbed TLS 在 Flipper Zero 中的实际裁剪与集成方式。贡献前快速检查清单Mbed TLS 项目欢迎社区提交 bug 报告与代码贡献所有 Pull Request 都会经过项目团队与社区评审且可能要求多次修改后才能被合并。在动手之前请对照官方 CONTRIBUTING.md 给出的四条快速检查项Sign-off所有提交commit必须包含Signed-off-by:签名行用于确认代码符合开发者原创证书DCO要求TestsPR 必须包含足以证明功能正确性或 bug 已修复的测试Changelog如涉及用户可见变更需要提供对应的 ChangeLog 条目Backports若缺陷同样存在于 LTS 分支需要提供回移植补丁可等主 PR 合并后再补这是允许的。这四项对应了后续章节的详细规则建议作为提交前的自查清单逐条核对。编码标准与贡献的通用要求官方指南对贡献代码提出了四条基本要求必须携带测试详见测试与持续集成测试两节。提交前先通过基础测试提交 PR 后再关注 CI 结果风格干净可读代码必须遵循 Mbed TLS 的编码标准clean and readable style可移植、面向全社区代码应以通用可移植的方式编写使整个社区受益而不是只满足个人需求安全性优先所有代码都会从安全角度被评审。这四条标准意味着贡献者在编写代码时就要同时考虑正确性、可移植性与安全性评审阶段也会围绕这三个维度展开。贡献流程五步法官方指南给出的提交流程分为五个步骤先讨论后动手查看已存在的 issue或围绕功能想法/bug 发起讨论避免重复劳动Fork 仓库并选择正确基线通常应以development分支为基底进行修改先写测试编写一个能证明 bug 已修复或功能符合预期的测试——测试先行是 Mbed TLS 一贯的开发模式提交 PR 并跟进评审与维护者协作直到合并发布。贡献可能需要多轮修改评审过程中一次或数轮 review 与修正都是正常现象控制 PR 规模为加快合并速度贡献应尽量短小、聚焦于单一功能或主题。贡献越大评审与合并所需时间越长。从仓库结构看这一流程与 Mbed TLS 自身的分支模型见 BRANCHES.md深度绑定development分支是下一个大版本4.0的孵化地因此以 development 为基底是保证改动最终进入主线的前提。向后兼容性API 变更的严格约束向后兼容是 Mbed TLS 的核心工程原则。项目力求用户升级到更新版本时无需修改任何自身代码除非用户主动选择使用新特性、切换到新世代库版本或变更因安全缺陷等原因确有必要。为达成这一目标官方制定了以下规则主开发分支与 LTS 分支均维持 API 兼容性详见 BRANCHES.md即使是在新增功能的主开发分支上任何 ABI/API 变更都必须有充分理由——或是显著增强、新功能或是必须通过接口变更才能解决的 bug禁止修改公共接口中函数的定义。接口只能通过扩展来演进需要变更的现有函数先标记为deprecated弃用若确需用新函数替代旧函数原型或文档化行为不同则创建一个具有新名称、新接口的函数旧函数保留并标记为弃用弃用函数会按计划、结构化地分批移除移除属于破坏性 API 变更必须给用户足够的预告期。从 BRANCHES.md 可看到更细的约定仓库采用语义化版本Semantic Versioningmain分支在次要版本间保持 API 兼容只有主版本号变更如 3.x → 4.0才会破坏 API。以下变更不视为兼容性破坏结构体/联合体中新增或重排字段、从结构中移除未文档化为公共的字段、枚举新增条目、函数返回了此前未文档化的新错误码、在多种错误条件并存时更换返回的错误码等。当安全与向后兼容冲突时安全优先但会尽量提供兼容选项。LTS 长期支持分支与回移植规则Mbed TLS 维护多个 LTS 分支在给定周期内持续维护。LTS 分支只接收安全修复与缺陷修复不引入可能改变代码体积或 RAM 占用的新特性/API 扩展——这对资源受限平台尤为重要。回移植到 LTS 分支必须遵守三条规则任何改变 API/ABI 的改动都不得回移植所有同时存在于 LTS 分支的缺陷修复都必须回移植。若某修复引入新函数等 API 变化应改写修复方案以避开 API 变更缺乏充分理由的 API 变更很难被接受新特性或增强不需要回移植例外是额外的测试用例或构建/测试脚本改进等质量提升。项目高度期望贡献者在提交development分支的同时主动将修复回移植到 LTS 分支。当前维护中的分支清单见 BRANCHES.md 的 Current Branches 一节其中明确列出了main、development、mbedtls-2.28与mbedtls-3.6等分支及其维护截止时间。测试要求function 文件与 data 文件的结构测试是 Mbed TLS 贡献的核心门槛——PR 必须包含证明功能正确性或 bug 已修复的测试若尚不存在此类测试。Mbed TLS 在 tests/ 目录下维护了一套全面的测试套件其组织方式是本项目测试体系的关键测试套件是动态生成的实际测试源文件如test_suite_rsa.c由一对模板文件生成function 文件如suites/test_suite_rsa.function包含测试函数定义data 文件如suites/test_suite_rsa.data包含测试用例以参数形式传递给测试函数。以仓库中实际存在的 tests/suites/test_suite_aes.ecb.data 为例其典型的用例格式为AES-128-ECB Encrypt NIST KAT #1 aes_encrypt_ecb:00000000000000000000000000000000:f34481ec3cc627bacd5dc3fb08f273e6:0336763e966d92595a567cc9ce537f5e:0每两条记录构成一个用例首行为用例名称次行为测试函数名 冒号分隔的参数本例中依次为密钥、明文、期望密文、预期返回码。这种function data分离的设计使得新增测试只需补充函数与数据而不必改动测试主框架。此外还有以下配套要求脚本 tests/scripts/basic-build-test.sh 可用于展示库的测试覆盖率新代码贡献应提供与库中既有代码相近的覆盖率水平如涉及示例程序应同步修改。持续集成测试与 git hooksPR 提交后会自动触发持续集成CI测试。贡献者需要跟进 CI 结果并修复失败项。官方建议在推送改动前启用 git hooks 脚本尽早捕捉问题。仓库中对应的脚本位于 tests/git-scripts其说明文档 README.md 给出了启用方法Git hooks 位于Mbed TLS root/.git/hooks不属于版本控制Mbed TLS 的 hooks 位于Mbed TLS root/tests/git-scripts需在.git/hooks中创建指向它的软链接例如在 Linux 上执行ln -s ../../tests/git-scripts/pre-push.sh pre-push注意当前 Mbed TLS 的 git hooks 仅支持 GNU 平台非 GNU 平台请勿启用这些脚本也可以独立运行。仓库中已提供pre-push.sh脚本即推送前自动执行检查的钩子。文档与 ChangeLog 要求Mbed TLS 文档体系完善官方指南要求贡献者在文档方面做到所有接口必须通过 Doxygen 记录新 API 必须引入 Doxygen 文档代码中复杂部分应包含注释必要时建议添加 Readme 文件若需要新增 Knowledge Base 文章应在 PR 描述中注明必须为贡献添加 ChangeLog 条目。ChangeLog 的完整规范见 ChangeLog.d/00README.md要点如下ChangeLog.d/目录存放尚未合并进主 ChangeLog 的待定条目需要条目的是用户可见变更库或示例程序中的 bug 修复含安全漏洞修复、行为修复、特定配置/平台构建修复、新特性/新示例程序/新平台支持、既有行为变更等一般不需要条目的是文档改进、性能改进除非特别显著、用户不直接交互的内部代码变更如测试代码与测试数据、普通编译器警告修复条目文件必须以*.txt结尾采用分类格式合法的分类为API changes、Default behavior changes、Requirement changes、New deprecations、Removals、Features、Security、Bugfix、Changes其余归入Changes格式细节每条条目以三个空格 星号 空格开头续行以 5 个空格开头行宽不超过 79 字符使用现在时与祈使句例如 Fix a bug in mbedtls_xxx() …涉及 issue 时使用#1234格式涉及 CVE 等外部引用也一并标注写作原则是Explain why, not how——面向库的使用者而非开发者bug 修复要说明 bug 的后果而非修复方法新特性要说明价值API 变更/弃用要说明如何迁移既有应用主 ChangeLog 的更新通过运行scripts/assemble_changelog.py将ChangeLog.d中的条目合并进主文件。许可、版权与 DCO 签署Mbed TLS 采用双许可模式这是贡献者必须理解的法律基础除文件中特别注明外Mbed TLS 文件以Apache-2.0 OR GPL-2.0-or-later双许可发布完整文本见 LICENSE用户可任选其一使用贡献者必须接受其贡献同时基于Apache-2.0 AND GPL-2.0-or-later两个许可证提交所有新文件应尽量包含标准 SPDX 许可证标识SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later版权归原作者保留新文件尽量在文件头部注释中注明Copyright The Mbed TLS Contributors提交代码时提交者与所有作者必须依据 dco.txtDeveloper Certificate of Origin开发者原创证书提交确认代码可以合法地成为项目的一部分并同时按 Apache-2.0 与 GPL-2.0-or-later 提交。DCO 的具体落实方式是在每条 commit message 中包含标准 Git 签名行Signed-off-by:若一个提交有多个贡献者每位贡献者都应添加自己的Signed-off-by:行。结合仓库源码Mbed TLS 在 Flipper Zero 中的集成作为补充观察 Flipper Zero 固件仓库是如何使用这个库的有助于理解贡献规则的现实背景。Flipper Zero 并未全量编译 Mbed TLS而是通过 lib/mbedtls.scons 做了按需裁剪构建脚本明确注释了 If we were to build full mbedtls, we would need to use this然后只选取aes.c、bignum.c、ecdsa.c、ecp.c、md.c、sha1.c、sha256.c、des.c等少量源文件参与编译。这正是 LTS 分支避免代码体积与 RAM 占用变化这一理念在嵌入式场景下的体现。配套的 mbedtls_cfg.h 是裁剪后的配置头文件通过MBEDTLS_CONFIG_FILE宏注入注释明确说明它只包含与 Flipper Zero 固件和应用相关的 Mbed TLS 配置子集需要更多特性时可以在应用中通过fap_private_libs引入完整 mbedtls或向仓库提 issue 请求加入默认配置。这种子集配置 按需扩展的用法正是 Mbed TLS 强调通过配置选项裁剪功能、且特性间互不影响enabling or disabling a cryptographic algorithm does not break code that does not use that algorithm的实践注脚。对贡献者而言这意味着当你在development分支新增算法或 API 时下游嵌入式集成方如 Flipper Zero是否启用该特性完全由各自的配置头文件决定——这正是官方向后兼容 配置化裁剪设计的价值所在。结语Mbed TLS 的贡献流程可以概括为一句话测试先行、风格可读、接口只扩不改、变更必须入档、提交必须签注。对照 CONTRIBUTING.md 的快速检查清单结合 BRANCHES.md 的分支策略、ChangeLog.d/00README.md 的条目规范与 tests/ 的套件结构任何贡献者都能以最小的返工成本提交出高质量 PR。【免费下载链接】flipperzero-firmwareFlipper Zero firmware source code项目地址: https://gitcode.com/GitHub_Trending/fl/flipperzero-firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考