Serial Studio 贡献指南从报告 Bug 到合入 Pull Request 的完整协作流程【免费下载链接】Serial-StudioOpen-source telemetry dashboard. Supports UART, BLE, MQTT, Modbus, CAN Bus and more.项目地址: https://gitcode.com/GitHub_Trending/se/Serial-StudioSerial Studio 是一个开源的遥测数据可视化平台telemetry dashboard支持 UART、TCP/UDP、BLE、MQTT、Modbus、CAN Bus、USB、HID、Audio、Process 等多种数据源并在其之上提供 15 可视化控件与可编程的帧解析能力。仓库采用“开源 GPL 模块 商业 Pro 模块”双轨授权结构代码库由core/下七个静态库与app/src组合根组成。本文基于仓库根目录的 CONTRIBUTING.md 展开结合仓库内的脚本、测试与 CI 配置系统说明如何高质量地向该项目提交 Bug 报告、功能建议、代码补丁、文档修订与测试用例——读完你可以完整走通从 发现一个问题 到 PR 被合入 的全流程。一、报告 Bug让维护者能一次性复现仓库要求所有 Bug 报告通过 issue 模板提交并明确给出了“最有价值”的报告应该包含的信息清单操作系统及版本例如 Windows 11 23H2 / Ubuntu 24.04 / macOS 14.5驱动与串口行为强依赖平台Serial Studio 版本与版本类型GPL 构建、试用版Trial还是 Pro 版。从 REUSE.toml 可以看到同一份源码按构建配置分别适用GPL-3.0-or-later与LicenseRef-SerialStudio-Commercial两种许可功能集合不同复现路径也不同连接类型UART、TCP/UDP、BLE、MQTT、Modbus、CAN Bus、USB、HID、Audio、Process。项目支持的数据源种类很多每种连接类型的故障排查路径完全不同复现步骤、预期行为与实际行为项目文件.ssproj与相关时的控制台输出.ssproj是工程文件格式包含连接配置、帧解析脚本、数据集与控件布局能极大加速定位控制台输出则对应帧解析与连接诊断信息。对涉及数据管线的缺陷仓库还提供了诊断计数spec 0033/0035 约定“诊断是拉取的不是推的”——帧读取与构建器的计数器以quint64增量形式在 1 Hz tick 上轮询见 tests/README.md 与core/Pipeline/相关源码报告中尽量附带这些统计信息可以显著提升定位效率。二、提出功能建议先讨论再写代码对于功能请求仓库的约定是想法已经成型走feature request issue 模板想法还在酝酿阶段可以在 Discussions 中开帖讨论较大规模的改动务必先在 issue 中把方案谈清楚再动手写代码让技术路线先达成一致。这条规则的底层逻辑与仓库的开发纪律一致从 CLAUDE.md 可以看到非平凡或多文件改动遵循 spec-driven 开发流程/ss-spec→/ss-plan→/ss-tasks→/ss-implement四个门控阶段方案先行是项目的一贯文化。贸然提交大 PR 而不先对齐思路很可能因为与既有架构例如core/严格分层、消息总线通信规则冲突而被要求大改。三、贡献代码双许可、格式规范与自动化检查3.1 先读懂 SPDX 许可头仓库欢迎对GPL 许可代码与商业Pro模块的贡献但每个源文件都带有 SPDX 头声明其许可条款动手之前必须先检查。典型的 SPDX 头形如 core/Core/SSAssert.h 中的SPDX-License-Identifier: GPL-3.0-or-later OR LicenseRef-SerialStudio-Commercial首方代码统一为GPL-3.0-or-later2026 年 7 月从-only重新授权而来。对 Pro 模块的贡献则按照下文所述的贡献者许可协议CLA条款接收。仓库整体是 REUSE 合规的REUSE.tomlLICENSES/目录共同声明了全部文件含第三方 vendored 库的版权与许可CI 中reuse lint是硬门禁。3.2 遵循 clang-format 配置代码格式以LLVM 基础风格、100 列、2 空格缩进为基准由仓库根目录的.clang-format定义。格式化工具被精确钉死在版本上——tests/requirements.txt 中clang-format23.1.0的注释明确说明clang-format 在不同版本间会改变自身默认行为因此.clang-format单独无法保证输出可复现必须配套固定版本的 wheel。提交前务必运行与你本地一致的格式化版本避免 CI 因格式差异失败。3.3 提交前必须通过两道检查CONTRIBUTING.md 明确了两条硬性纪律scripts/code-verify.py --check # 结构性 风格规则检查CI 同款 scripts/sanitize-commit.py # 一键跑完整管线scripts/code-verify.py 是项目自定义的结构性 linter执行 clang-format 无法表达的规则QML 中id:必须位于对象块内第一行非注释位置且后跟空行、单赋值属性按总渲染长度“圣诞树”排序、无花括号单语句体后必须空一行、行尾注释与 AI 叙事式注释检测等。--check只报告不修改并重新生成.code-report--fix直接改写文件。某些区域可用// code-verify off/// code-verify on围栏豁免但豁免本身会触发代码评审关注。scripts/sanitize-commit.py 是提交前的一站式流水线按序执行权限规范化 →expand-doxygen.py将 Doxygen 注释规范为三行式 → clang-format 两遍中间夹code-verify.py --fix→clang-tidy-verify.py可选→ 两个单例/翻译单元规模棘轮 → black 格式化 Python →documentation-verify.py文档检查 →claim-verify.py文档声明核验 → SDK 与属性注册表生成 → 基线清单刷新 → 最后再跑code-verify.py --check生成最新.code-report。注意 sanitize 只清理绝不替你 commit 或 push。3.4 风格细则的完整定义位置详细风格规范格式、命名、头文件布局、信号槽、注释与 Doxygen、QML、性能、NASA Power of Ten 安全关键规则十条位于 doc/claude/code-style.md仓库级协作规则含热路径、组合根、子系统契约、Threading Hotpath 等不可协商约束位于 CLAUDE.md。几条对新贡献者最关键、最容易踩坑的风格要求命名类型CamelCase函数camelCase局部变量与公开成员lower_case静态s_前缀、私有成员m_前缀、常量kCamelCase、宏UPPER_CASE控制流最多 3 层嵌套单语句体不加花括号函数 40–80 行为目标、100 行硬上限翻译单元不超过 1500 行头文件[[nodiscard]]用于所有非 void 返回值禁止Q_INVOKABLE void改用public slots:禁止头文件内成员初始化信号槽用Q_EMIT而非emit禁止SIGNAL()/SLOT()宏禁止用disconnect(nullptr)作槽应捕获QMetaObject::Connection注释代码即规格。函数体内部不允许注释cxx-inbody-comment规则必要的原因性说明折叠进函数上方的单行/** brief ... */禁止行尾注释与 AI 叙事式注释断言使用SS_ASSERT(cond, action)定义于 core/Core/SSAssert.h条件在每个构建中都会求值Debug 中止、Release 每站点报告一次并执行恢复动作热路径内核用SS_ASSERT_HOTPATH。3.5 公开 API 必须写 Doxygen 注释新增公开 API 需要添加 Doxygen 注释.h中每个类型级定义一个/** brief ... */.cpp中每个函数定义一个并避免行尾行内注释。四、提交变更的完整流程按 CONTRIBUTING.md 的步骤Fork 仓库创建功能分支git checkout -b feature/my-change提交信息要有描述性descriptive messages说明为什么而非是什么推送到你的 fork 并打开 PR使用 PR 模板确保 CI 通过尤其是改动接近数据管线hotpath时必须通过热路径基准门禁。关于第 4 点的“CI 门禁”从 .github/workflows/ci.yml 可以看到其真实构成单元测试层ctestcmake -G Ninja -B build/unit-ci ... cmake --build build/unit-ci --target ss_unit_tests ctestQML lintss_qmllint目标输出与app/qml/qmllint-baseline.json基线对比新出现的 finding 会导致失败热路径基准门禁--headless --benchmark-hotpath --min-fps 256000 --benchmark-output benchmark.txt以 256 kHz 为硬门禁默认--min-fps256000PGO 优化构建下每个 push/PR 都执行应用内自测--headless --selftest-suite qml实例化全部 QML 文件大规模数据库加载测试、sanitizer 作业ASanUBSan / TSan等。因此合入前的验证远不止“能编译”还包括吞吐、QML 合法性与内存安全。五、贡献者许可协议CLA向本仓库提交贡献即表示你同意以下条款CONTRIBUTING.md 全文照录的要点你证明certify该贡献是您的原创作品或您拥有提交它的合法权利您在法律上有权授予下文所述权利若代表实体例如雇主提交您已获得该实体的许可。你向 Alex Spataru 授予永久、全球、免版税、不可撤销、非独占的许可使用、复制、修改、改编、发布、分发、再许可并创作您贡献的衍生作品在GNU GPL v3与Serial Studio Commercial License含两者的未来版本下许可该贡献。你同意您的贡献可同时用于开源软件与商业授权软件贡献的任何部分均不受会阻碍其商业使用或分发的专利或其他知识产权限制未来不会撤销或质疑该许可授予。范围定义“贡献”指任何原创著作包括对现有内容的修改或增补通过 PR、issue 或任何拟纳入项目的电子通信形式提交。六、贡献文档帮助页与示例帮助页位于doc/help/例如 Getting-Started.md、Data-Sources.md、Plots.md 等 60 篇随应用分发的手册示例说明位于examples/例如 CAN Bus Example、Modbus PLC Simulator、LorenzAttractor 等每个示例目录下还有doc/配图与 README。提交文档前运行scripts/documentation-verify.py它会对随应用分发的全部 Markdown 做 lint。从脚本头部的规则说明可以看到它检测的典型问题营销式措辞escape hatch、magic、seamless、教程腔well、lets、对话式开头If youve ever、编辑腔powerful、elegant、填充词essentially、just、simply、夸张词blazing fast、world-class、正文感叹号、用--伪造破折号等——每类都会写入根目录的.doc-report供人工或 LLM 跟进修正。写文档时同样要注意仓库根目录的 REUSE.toml 将doc/**、examples/**一并声明为GPL-3.0-or-later OR LicenseRef-SerialStudio-Commercial与代码贡献适用相同的许可条款。七、测试四层测试体系的运行方式测试套件位于tests/完整目录结构、fixture、marker 与操作模式表见 tests/README.md。CONTRIBUTING.md 给出的两条核心命令是pip install -r tests/requirements.txt pytest tests/scripts/ -v # 解析器单元测试无需运行应用 pytest tests/integration/ -v # 需要已运行且开启 API 服务器的实例各层测试的依赖与前置条件如下层级目录前置条件说明集成测试tests/integration/运行中的 Serial Studio Settings Miscellaneous Enable API Server端口 7777通过 TCP API 驱动运行实例模拟设备遥测并断言解析/导出/显示结果安全测试tests/security/同上对 TCP API 服务器的边界与韧性测试性能测试tests/performance/同上基于 pytest-benchmark 的吞吐基准脚本单元测试tests/scripts/仅需 Node.jsJS 帧解析器单元测试每次调用run_parser()都派生全新 Node 子进程无共享状态工具链测试scripts/tests/无对code-verify.py与 CI 工作流的 fixture 驱动测试C 单元测试app/tests/ctest非 pytestQt Test 套件只链接被测生产 TU配置-DSS_BUILD_TESTSON模糊测试app/tests/fuzz/ctest 或 libFuzzer不可信字节入口点 检入语料库集成/安全/性能测试的统一模式是连接SerialStudioClient连接localhost:7777→配置API 设置操作模式、定界符、校验和、JS 解析器→模拟DeviceSimulator在localhost:9000起 TCP/UDP 服务器→推流→断言→清理。大部分样板由conftest.py的api_client、device_simulator、clean_state等 fixture 承担。C 层则覆盖校验和、环形缓冲区、DSP 内核、帧定界、异步引擎、X/Y/ZMODEM、OPC UA 安全、水瀑布贴图等大量子系统完整套件清单见 tests/README.md。实用提示帧解析问题优先用脚本测试定位无需 GUI涉及连接/导出/显示的问题用集成测试提交解析器改动前把对应脚本先纳入tests/scripts/test_frame_parsers.py已覆盖 28 种解析器类会更稳妥。八、问题咨询使用 Discussions 提出疑问使用帮助中心查阅用法文档。需要注意在 issue/PR 中提问时务必带上前述的 Bug 报告要素版本类型、连接类型、.ssproj否则维护者很难给出有效答复。结语一份贡献的完整检查清单对照 CONTRIBUTING.md 与仓库实际门禁一份合格的贡献应满足Bug/特性先经 issue 对齐大改动必须方案先行许可读懂目标文件的 SPDX 头Pro 模块贡献默认接受 CLA 条款格式clang-formatLLVM 基础、100 列、2 空格code-verify.py --check提交前跑scripts/sanitize-commit.py一键完成格式化、结构校验、文档检查与注册表/SDK 生成文档改动文档先跑scripts/documentation-verify.py测试按改动范围补齐脚本测试、集成测试或 C ctest 套件PRfork feature 分支 描述性 commit 模板 PR等待 CI含 256 kHz 热路径基准门禁通过。遵循这套流程你的贡献就能以维护者最容易审查、机器人门禁最容易通过的方式进入这个遥测平台项目。【免费下载链接】Serial-StudioOpen-source telemetry dashboard. Supports UART, BLE, MQTT, Modbus, CAN Bus and more.项目地址: https://gitcode.com/GitHub_Trending/se/Serial-Studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考