Cppcheck 贡献指南：从提交 PR 到测试、定位与翻译的完整开发流程

• 开发工具
• 静态分析
• 代码质量
• 质量保障

这篇技术指南面向有意为 Cppcheck（C/C++ 静态分析工具）贡献代码、测试、缺陷修复或翻译的开发者，系统梳理仓库根目录下 CONTRIBUTING.md 所规定的协作规范，并结合test/、externals/simplecpp/、gui/、tools/等目录中的真实实现进行源码级印证。读完你将掌握：PR 提交流程与评审预期、单元/集成测试的编写与"预期失败"标记约定、simplecpp预处理器的协作边界，以及 GUI 翻译文件的维护方式。

一、代码变更：PR 流程与协作预期

Cppcheck 的代码贡献统一通过 GitHub Pull Request 提交（对应 CONTRIBUTING.md 中 "Code Changes" 一节）。需要注意几点协作预期：

• 响应可能延迟：维护团队规模很小，PR 可能无法立即获得回复，也可能与当前开发范围或时间安排冲突，因此请耐心等待。
• 可能被拒绝：任何类型的贡献都受欢迎，但维护者保留拒绝权；通常被拒绝时会给出原因，且一切结论都可以继续讨论。
• externals目录的例外：externals/下的第三方库改动应提交给对应的上游项目，随其下一个稳定版本同步引入。唯一例外是externals/picojson/picojson.h—— 该项目已不再维护（对应 Trac ticket 12233），其变更处理方式尚未最终确定。这一点与仓库实际结构一致：externals/目录下确实以独立子项目形式存放着picojson/、simplecpp/、tinyxml2/三个第三方库（见 externals/）。
• 提交后保持跟进：PR 提交后请准备好回答评审问题与反馈；"提交完就消失"（dump and leave）会降低合入概率。这一要求同样适用于合入之后——CI 未暴露的问题可能在后续使用中才浮现。
• 不要因拒绝而气馁：评审过程未必一帆风顺，但这不代表你的贡献没有价值。

从仓库实现看，核心库通过 lib/CMakeLists.txt 链接simplecpp、picojson、tinyxml2与 PCRE，这印证了"第三方依赖与核心代码分离维护"的架构：externals/中的库作为上游同步的依赖被集成，而核心检查逻辑位于lib/。

二、测试要求：每个改动都要配套测试

文档明确要求：每项改动都必须附带测试，以防止未来变更引入回归。

• C++ 单元测试：位于test/目录（仓库实际有 78 个test/test*.cpp测试文件，如 test/testbufferoverrun.cpp、test/testnullpointer.cpp、test/testvalueflow.cpp 等）。
• Python 集成测试：位于 test/cli/ 目录，仓库实际包含 25 个*_test.py文件（如helloworld_test.py、other_test.py、unused_function_test.py），配合 test/cli/testutils.py 等工具运行。
• 负向测试更受欢迎：测试相反行为（负向测试）更有利，但根据改动类型可能非必需，也可能已存在。
• 预期失败必须有 ticket：引入TODO_ASSERT_宏或@pytest.mark.skip/@pytest.mark.xfail标记的测试，都必须提交对应的 bug tracker ticket 跟踪。

2.1 C++ 测试框架：TestFixture 与断言宏

C++ 单元测试基于 test/fixture.h 中的TestFixture基类。它继承ErrorLogger，提供assertEquals、todoAssertEquals、assertThrow等一系列断言，并通过ASSERT、ASSERT_EQUALS、ASSERT_NO_THROW等宏封装（见 test/fixture.h 中TEST_CASE、ASSERT、TODO_ASSERT_*宏定义）。

例如 test/testbufferoverrun.cpp 中就大量使用了TODO_ASSERT_EQUALS表达"当前行为尚未正确、期望值与实际值不一致"的测试。这类宏的语义是：期望值（wanted）与当前值（current）不符时测试不失败，但会单独统计——配合TODO_计数机制，让维护者能区分"真实失败"与"已知待改进项"。

TestFixture还提供SettingsBuilder（见 test/fixture.h 中的SettingsBuilder类），可用链式调用配置测试所需的Settings，例如settingsBuilder().severity(...)、.cpp(...)、.platform(...)，让单元测试可以精确控制分析选项。

2.2 Python 集成测试：pytest 标记约定

集成测试使用 pytest 的 skip/xfail 机制。仓库实测数据（test/cli/other_test.py）显示典型用法包括：

• @pytest.mark.skipif(sys.platform == "win32", reason="TTY not supported in Windows")—— 平台相关跳过；
• @pytest.mark.skip—— 无条件跳过，且通常伴随# TODO: ...注释说明原因；
• @pytest.mark.xfail(strict=True)—— 预期失败，strict=True意味着若测试意外通过反而会报错；
• 依赖外部工具（如clang-tidy）的测试会使用@pytest.mark.skipif(not __has_clang_tidy, reason='clang-tidy is not available')。

文档强调：这类 skip/xfail 标记都应配套 ticket，保证"预期失败"是被跟踪的、有理由的，而不是长期遗留的盲区。

2.3 CI 的 "always green" 策略

CI 已经承担了大量验证工作，但有些部分无法自动保证。项目的核心约束是"always green"（始终绿灯）：不允许测试失败。相应地：

• 偶尔抖动的 flaky 测试可能被容忍，但必须有 ticket 跟踪；
• 引入预期失败的测试时，C++ 侧应使用TODO_*宏，Python 侧应使用@pytest.mark.xfail(strict=False)注解；
• 通常可以在自己的 fork 上运行 CI 提前验证 PR（不过当前仓库的 CI 为避免重复构建做了调整，这一能力可能受限——文档中以 TODO 形式记录待补的 ticket）。

三、目标问题类型：优先修什么

Cppcheck 的问题跟踪在 https://trac.cppcheck.net（仓库内多处引用，如releasenotes.txt、代码注释中的 ticket 编号），ticket 没有严格优先级排序（除非常规的崩溃类问题），但以下三类最受关注：

如果你开始处理某个 ticket，请先自行认领（assign yourself）或请求被分配，避免多人在同一问题上重复工作。

3.1 从源码看"低误报"目标

仓库中 man/checkers/ 目录以每个检查项一篇文章的粒度维护检查器文档（如arrayIndexOutOfBounds.md、nullPointer.md等），samples/ 目录则按检查项存放可复现的正反例代码。这些结构从侧面印证：维护者高度关注每个检查项的行为与误报边界，贡献者修 bug 时也应遵循同样的标准——先复现、再定位、后验证。

四、源码级 TODO：动手前先沟通

仓库源码中还散布着各种source-level TODO（源级 TODO 注释）。这些 TODO 可能：

• 与已跟踪的 issue 相关（即使没有显式注明）；
• 只是探索性遗留、被过度添加，甚至可能已经过时。

因此文档建议：如果要在这些 TODO 上投入大量时间，先与维护者取得联系，避免在已过时或废弃的方向上浪费精力。这一约定与仓库中的实际情况吻合——lib/、test/ 各源码文件中都散落着TODO:注释，例如 test/fixture.h 中SettingsBuilder对 C/C++ 标准处理的TODO: CLatest and C23 are the same注释。

五、simplecpp：核心预处理器的独立协作

Cppcheck 的核心依赖simplecpp库——一个从 Cppcheck 独立出来的预处理实现。它的定位在头文件中有明确描述："A simple and high-fidelity C/C++ preprocessor library"（见 externals/simplecpp/simplecpp.h）。

• 独立项目与独立跟踪：simplecpp由 Cppcheck 开发者维护，但拥有自己的项目与 bug tracker，对它的贡献同样欢迎，且应直接提交到其上游，而不是本仓库的externals/目录。
• 在核心流程中的位置：从源码看，Cppcheck 的分析管线在预处理阶段调用simplecpp::preprocess。以 lib/preprocessor.cpp 中的Preprocessor::preprocess()为例，它构造simplecpp::DUI（Define/Undefine/Include 配置）与simplecpp::TokenList，然后调用simplecpp::preprocess(...)完成宏展开、条件编译与文件包含，并收集MacroUsage（宏使用情况）与IfCond（条件表达式）供后续检查使用（见 lib/preprocessor.cpp 中preprocess与getcode的实现）。整个lib/目录中simplecpp::命名空间被大量引用（如preprocessor.cpp117 处），可见其是 Cppcheck 分析引擎的基石。
• 贡献含义：修改预处理器行为（宏展开、#if条件求值、包含解析等）时，应优先在上游 simplecpp 项目中修改并测试，Cppcheck 侧通过同步依赖获得改进。

六、翻译：为 cppcheck-gui 贡献本地化

Cppcheck 还维护cppcheck-gui的多种语言翻译。仓库 gui/ 目录下实际存放了 14 个 Qt 翻译文件（.ts）：cppcheck_de.ts（德语）、cppcheck_es.ts（西班牙语）、cppcheck_fi.ts（芬兰语）、cppcheck_fr.ts（法语）、cppcheck_it.ts（意大利语）、cppcheck_ja.ts（日语）、cppcheck_ka.ts（格鲁吉亚语）、cppcheck_ko.ts（韩语）、cppcheck_nl.ts（荷兰语）、cppcheck_ru.ts（俄语）、cppcheck_sr.ts（塞尔维亚语）、cppcheck_sv.ts（瑞典语）、cppcheck_zh_CN.ts（简体中文）、cppcheck_zh_TW.ts（繁体中文）。

贡献翻译时请注意：

• 现有翻译可能不完整或已过期，欢迎补充完善；
• 也接受新增语言，但此类贡献必须完整（不能只翻译部分字符串）；
• 翻译清单由 gui/gui.pro 中的TRANSLATIONS变量统一登记，新增语言时需同步在该工程文件中注册.ts文件。

七、贡献清单速查

综合全文，一次高质量的 Cppcheck 贡献可以按以下清单自查：

1. 改动范围：核心代码改动直接提交 PR；externals/（simplecpp、tinyxml2）的改动先提交到各自上游；picojson例外需先与维护者确认处理方式。
2. 测试配套：C++ 改动附 test/ 下的单元测试，CLI/集成行为改动附 test/cli/ 下的 pytest 测试；优先写负向测试。
3. 预期失败管理：使用TODO_ASSERT_*（C++）或@pytest.mark.xfail/skip（Python）时必须关联 ticket，并遵循 CI 的 "always green" 约定。
4. 行为变更登记：新增功能或修复 bug 时，在 https://trac.cppcheck.net 中登记条目。
5. 优先级参考：误报（False Positive）> 检测回归（Detection Regression）> 其他缺陷（Other Defect）；动手前先认领 ticket。
6. 源码 TODO：涉及 source-level TODO 的深度工作，先与维护者沟通。
7. 翻译：补全现有.ts文件或完整新增语言，并在 gui/gui.pro 注册。
8. 跟进：PR 提交后保持响应，合入后同样关注后续反馈。

按照上述规范提交的贡献，将最大程度地契合 Cppcheck 的评审流程与质量底线，从而提高被合入的概率。

• 开发工具
• 静态分析
• 代码质量
• 质量保障