参与 JSON for Modern Cnlohmann/json贡献指南从问题报告到合并拉取请求的完整工程规范【免费下载链接】jsonJSON for Modern C项目地址: https://gitcode.com/GitHub_Trending/js/json本篇指南围绕本仓库官方《贡献指南》源码位于 .github/CONTRIBUTING.md并被文档站点通过 mkdocs include 指令--8--嵌入为 社区贡献指南页面展开系统讲解这个 JSON 库维护者期待的外部贡献流程如何提交高质量 bug 报告、如何以测试优先的方式修复问题、如何更新官方文档、如何在修改源码后重新生成单头文件版本以及哪些改动会被视为破坏性修改。读完本文你将掌握一套可直接照做的开发与提交流程理解仓库中 tests/src、include/nlohmann、single_include/nlohmann 三大目录之间的生成与校验关系从而显著提高你的 Pull Request 被合并的概率。一、先理解文档的结构与定位docs/mkdocs/docs/community/contribution_guidelines.md文件本体只有一行 mkdocs 引用语法--8-- ../../../.github/CONTRIBUTING.md其作用是把仓库根目录下.github/CONTRIBUTING.md的内容在文档构建时按原样嵌入页面。这意味着贡献指南的唯一事实来源是.github/CONTRIBUTING.md站点页面只是它的渲染视图——对仓库文档做任何修改都必须改.github/CONTRIBUTING.md而不是改渲染页。整份指南共分四大部分Ways to Contribute列出四种参与方式报告 bug、报告安全漏洞、讨论新特性、提交修复。How to…细化每次改动需要满足的四项硬性动作描述改动、关联 issue、编写测试、更新文档外加一项工程流程重新合并源文件 amalgamate。Please dont…三条红线——不破坏公共 API、不破坏 C11 语言一致性、不破坏 JSON 一致性。Wanted维护者明确求贤若渴的三个方向。下文将逐节结合仓库中的真实文件与脚本展开。二、四种参与方式从 Issue 到 Discussion 到 PR2.1 报告 Bug按模板提交可复现的最小示例维护者要求先检索 .github/ISSUE_TEMPLATE/bug.yamlGitHub Form 风格的 Issue 模板确认没有重复问题再创建新问题。该模板给出了非常具体的字段约束可作为撰写 bug 报告的清单模板字段需要填写的内容目的Description抽象描述问题现象并说明为何认为是 bug尽量附上文档、JSON 规范或代码的定位帮助维护者判断性质Reproduction steps分步描述触发方式保证可复现Expected vs. actual results期望行为与实际行为明确差异Minimal code example一个小而自包含、能稳定触发 bug 的示例仓库明确注明无法分析大型代码库且不要贴截图大幅缩短定位时间Error messages编译错误、异常信息、栈回溯等辅助诊断Compiler and operating system编译器版本与操作系统且需确认在受支持编译器列表内排除环境问题Library version发布版本号如 3.12.0或 commit hash若来自包管理器需注明来源精确定位版本行为差异Validation勾选在 develop 分支最新版本上仍可复现以及可成功编译并运行单元测试过滤已被修复或环境导致的问题指南还特别要求若遇到编译错误请务必附上编译器版本、操作系统和相关部分的错误原文若是提案新功能应给出改进后代码的示例与用法。2.2 报告安全漏洞走独立通道安全漏洞不要走普通 Issue而是按照仓库根目录的 .github/SECURITY.md 中描述的安全策略单独上报以控制披露节奏。2.3 讨论新特性先开 Discussion对于疑问、特性请求与支持请求维护者建议先创建 Discussion 而不是直接开 Issue当某个回答解决了问题时请点击Mark as answer方便后来读者和社区对未解决问题做筛选。这一机制直接对应仓库中 .github/ISSUE_TEMPLATE/config.yml 对 Issue 入口的分流设置。2.4 提交修复先沟通、再开 PR、须签 DCO提交修复前应在进行中的 Discussion 或既有 Issue 下先发表评论避免重复劳动和后期 review 阶段的摩擦。正式的 Pull Request 需要满足 .github/PULL_REQUEST_TEMPLATE.md 中的清单改动有 what 和 why 的详细描述尽可能关联既有 issue每一行新代码都有对应测试行覆盖率维持在 100%文档随功能同步更新运行过make amalgamate重新合并源码。此外所有贡献包括 PR必须同意Developer Certificate of OriginDCO1.1 版——即 Linux 内核社区采用的那份开发者原创性认证声明贡献者有权将该补丁纳入本项目。三、How to每次 PR 前必须完成的五项工作3.1 描述清楚 what 与 why这是一个典型的业余时间维护的开源项目原话primarily maintained as a spare-time project维护者无法承诺合并与发布的速率。因此指南反复强调只讲改了什么不够还要讲为什么这样改——这段 rationale 在未来数年后讨论相关改进或 bug 时依然极具价值。在 review 时把 what/why 写清楚是让改动快速过关最有效的手段。3.2 引用既有 Issue通过将 PR 链接到对应 Issue可以明确修复正在进行中、合并后应关闭哪个 Issue。除修 typo 这类少数情况外都不应跳过事先讨论。3.3 编写测试100% 覆盖率是硬约束If you liked it, you should have put a test on it.仓库拥有庞大测试套件覆盖库的几乎全部代码路径这些测试对维持 API 稳定性至关重要。仓库实测证据如下全部单元测试位于 tests/src按功能领域命名例如unit-json_pointer.cpp、unit-conversions.cpp、unit-serialization.cpp、unit-binary_formats.cpp等测试基于 tests/thirdparty/doctest/doctest.hdoctest 框架断言风格为CHECK宏修复 bug 时默认把回归用例追加到 tests/src/unit-regression2.cpp并以被修复的 issue 编号命名小节形成每个历史 bug 对应一条回归测试的可追溯结构。3.3.1 改动前先跑通测试基线指南要求在动手前先确认测试套件全绿。命令如下cmake -S. -B build cmake --build build -j 10 ctest --test-dir build -j 10预期输出形如100% tests passed, 0 tests failed out of 98具体用例数量以仓库当前 tests/CMakeLists.txt 中add_test注册的测试为准这里 98 仅为文档给出的一次数值示例。测试基础设施的实际配置可查阅 cmake/test.cmake。3.3.2 异常测试必须用 CHECK_THROWS_WITH_AS指南特别规定测试异常时必须使用CHECK_THROWS_WITH_AS因为该宏除断言抛出了指定异常类型外还会同时校验抛出异常的what()消息内容。这一点在实际测试代码中有大量落点——例如 tests/src/unit-json_pointer.cpp 中就存在约 50 处CHECK_THROWS_WITH_AS断言用来验证json_pointer各类越界与非法访问既抛出正确的异常类型如json::out_of_range、json::parse_error又携带符合预期的错误文本。3.3.3 覆盖率下降会自动告警如果测试覆盖率出现下降PR 上会自动收到一条警告评论CI对应 .github/workflows/ubuntu.yml 等流程会产出覆盖率报告产物供你查阅。因此提交前在本地尽量补齐新分支的用例是最省时的做法。3.4 更新文档库的在线文档由 docs/mkdocs/docs 目录下的 Markdown 源文件经 mkdocs 生成其中包含针对各功能领域的专题页位于 docs/mkdocs/docs/features全部异常类型清单页位于 docs/mkdocs/docs/home 下的 exceptions 文档覆盖每个公共 API 函数的详尽 API 参考位于 docs/mkdocs/docs/api。本地构建并预览文档的命令为make install_venv -C docs/mkdocs make serve -C docs/mkdocs这两条命令背后对应的实际目标定义在 docs/mkdocs/Makefile 中install_venv会创建 Python 虚拟环境并按 docs/mkdocs/requirements.txt 安装依赖serve会先执行style_check即用 scripts/check_structure.py 校验文档目录结构随后启动本地服务器。文档默认在http://127.0.0.1:8000/预览。站点还提供buildCI 中用于校验文档可构建与link_check启用 htmlproofer 检查失效链接等目标动手改文档前可先在本地跑通build。3.5 Amalgamate单头文件是生成物绝不能手改这是本项目最独特的工程约束。仓库同时维护两套源码形态多文件形态源码位于 include/nlohmann含detail/下 input/output/meta/iterators 等子模块是开发与测试的实际对象单头文件形态single_include/nlohmann/json.hpp 与 single_include/nlohmann/json_fwd.hpp是用户#include nlohmann/json.hpp实际引用的发行物。单头文件由多文件形态自动生成直接编辑single_include属于违规操作。正确的姿势是修改include/nlohmann下的源码然后执行make amalgamate该目标在根目录 Makefile 中定义为先用 tools/amalgamate/amalgamate.py 按 tools/amalgamate/config_json.json 的配置把 include/nlohmann 各源文件拼接生成两个单头文件随后调用make pretty用Artistic Style对源码做统一格式化。两个需要格外注意的工程细节make amalgamate触发的 astyle 格式化会就地修改源码文件提交前务必 review 相关 diff避免把无关的格式化噪音混入提交CI 中设有专门的防回归检查——对应 Makefile 的check-amalgamation目标以及 .github/workflows/check_amalgamation.yml、.github/workflows/comment_check_amalgamation.yml 工作流。它会先把现有单头文件挪走、现场重新生成一份再用diff比对。若不一致即构建失败并提示请阅读贡献指南后重新 amalgamate。这从机制上保证了提交进仓库的单头文件一定与include/nlohmann源码同步。四、三条红线哪些改动会被拒绝4.1 不破坏公共 API库采用语义化版本semver大量跨行业的既有用户依赖 3.x.y 版本的 API 契约因此以下改动被明确禁止修改函数签名参数类型、返回类型、参数个数或成员函数的 const 限定删除函数重命名函数或类改变异常处理方式或异常 id改变访问限定符access specifier改变默认参数。需要渐进式引入破坏性行为时唯一被认可的做法是用特性宏feature macro将其罩住例如 JSON_USE_IMPLICIT_CONVERSIONS。用户在下一个大版本到来之前可以通过定义该宏提前切换行为并测试自己的代码为正式弃用旧行为铺路——这正是本仓库管理 API 演进的标准范式。4.2 不破坏 C11 语言一致性库的目标是兼容C11 及以后的所有受支持编译器。指南明确指出 GCC 4.7及更早、Clang 3.3及更早、MSVC 13.0及更早因 C11 支持不完整而无法工作。因此不要引入这些受支持编译器无法编译的新特性对依赖 C14 及更高标准的功能必须用 JSON_HAS_CPP_14 一族版本探测宏包起来仓库 include/nlohmann/detail/macro_scope.hpp 等处可看到这类宏在编译期对语言版本做分支的实际用法保证低版本标准下自动降级、绝不硬编译失败。4.3 不破坏 JSON 一致性不得提出会使库偏离RFC 8259所定义的 JSON 数据交换格式的改动若确属对 JSON 的合规扩展必须给出充分动机说明。考虑到该库以解析正确性与规范符合度为核心卖点任何方言化倾向都会被审慎对待。五、维护者最期待的三个贡献方向指南末尾明确了最受欢迎、且长期开放的贡献领域扩展持续集成矩阵向更小众的编译器与平台扩展 CI例如 Android NDK、Intel 编译器、以及 Clang 的激进开发版本。仓库现有 CI 布局可参考 .github/workflows 下的ubuntu.yml、windows.yml、macos.yml等文件新增平台只需照葫芦画瓢追加 workflow。提升 JSON 解析器效率当前解析器是一个带手写字符串处理的朴素递归下降解析器。维护者欢迎更精巧的解析思路例如 LALR 类方案但同时坦率地说明了约束——Bison、ANTLR 等解析器生成器难以与单头文件形态共存解析逻辑必须留在json.hpp头文件内。如果你关注过 re2c 这类可内联到 C 头文件的扫描器方案这个方向很适合你。扩充与更新基准测试仓库的 benchmark 工程位于 tests/benchmarks入口为 tests/benchmarks/src/benchmarks.cpp维护者欢迎把本库最新版本纳入更广泛的性能对比中——速度与内存占用始终是 C 开发者最关心的特性。六、可继续深入阅读的仓库资料以下资料都在本仓库内可作为理解贡献流程上下游的补充阅读README.md库的功能总览与受支持编译器清单是理解任何改动的起点docs/mkdocs/docs/api/macros全部特性宏与配置宏的官方说明改动涉及宏时务必对照docs/mkdocs/docs/api逐函数级别的 API 参考撰写文档 PR 时以此为格式基准tests/CMakeLists.txt查看测试注册方式与新增测试文件的接入方法.github/SECURITY.md 与 .github/CODE_OF_CONDUCT.md安全上报渠道与社区行为准则ChangeLog.md了解版本演进与变更记录的组织方式便于让新功能描述对齐项目的写作风格。总结向 JSON for Modern C 提交贡献本质上是在遵守一套测试驱动 生成物受控 三红线保护的工程纪律。只要做到——先 Discussion 再动手、bug 修复必带指向 issue 的回归测试且使用CHECK_THROWS_WITH_AS、文档与源码同步更新、最终以make amalgamate重新生成单头文件并跑通全量ctest——你的 PR 就能顺畅地进入 review 流程成为这个被广泛使用的 C JSON 库持续演进的一部分。【免费下载链接】jsonJSON for Modern C项目地址: https://gitcode.com/GitHub_Trending/js/json创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考