From d33068da730aa1ffa3f1acb332e36653681efa2c Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Thu, 8 Oct 2026 17:44:34 +0200 Subject: [PATCH] Address review comments on the API stability docs and a test comment (#5784) * Address review comments on #5775 and #5779 Allow new defaulted parameters and new default arguments in the API stability rules, mention the macro opt-in, and drop the redundant recompile advice. Describe test-diagnostics-optimized as the regression test for the fixed #5742. Signed-off-by: Niels Lohmann * Document what counts as a breaking change in the API stability rules Spell out the 3.x compatibility rules in the roadmap: new defaulted parameters, new default arguments, noexcept/constexpr, template parameters, parse and dump results, accepted input, key iteration order, iterator invalidation, implicit conversions, to_json/from_json lookup, json_sax, value_t enumerators, and documented macros, CMake options and headers. Also list std::hash values as not part of the public API, and link the macro overview from the section. Signed-off-by: Niels Lohmann --------- Signed-off-by: Niels Lohmann --- docs/mkdocs/docs/community/roadmap.md | 32 +++++++++++++++++++-------- tests/CMakeLists.txt | 3 ++- 2 files changed, 25 insertions(+), 10 deletions(-) diff --git a/docs/mkdocs/docs/community/roadmap.md b/docs/mkdocs/docs/community/roadmap.md index 27afeb4c5..1b1f287a9 100644 --- a/docs/mkdocs/docs/community/roadmap.md +++ b/docs/mkdocs/docs/community/roadmap.md @@ -36,13 +36,26 @@ work items are tracked in the [GitHub milestones](https://github.com/nlohmann/js ## API stability Releases follow [semantic versioning](https://semver.org): a minor or patch release of version 3.x does not break code -that uses the public API. In particular, a 3.x release does not: +that uses the public API, unless that code opts in to a change with a macro as described [below](#version-40). In +particular, a 3.x release does not: -- change the signature of a function (its parameter types, return type, number of parameters, or the const-ness of a - member function); -- remove or rename a function or class; +- make breaking changes to the signature of a function: the types or order of its existing parameters, its return type, + its `noexcept` or `constexpr` specifier, or the const-ness of a member function. New parameters may be added if they + have a default value; +- remove or rename a function or class, or change the template parameters of a public class template; - change which exceptions a function throws, or the [exception ids](../home/exceptions.md); -- change access specifiers or default arguments. +- change access specifiers, or change or remove existing default arguments. New default arguments may be added; +- change the JSON type that a valid input parses to, or the text that `dump()` produces for a valid value; +- accept input that was rejected before, or reject input that was accepted before; +- change the order in which the keys of an object are iterated. The default type sorts keys, and + [`ordered_json`](../api/ordered_json.md) keeps insertion order; +- change when iterators, pointers, or references are invalidated, or the state of a moved-from `basic_json`; +- add or remove implicit conversions from `basic_json`; +- change how `to_json` and `from_json` functions are found, or the behavior of + [`adl_serializer`](../api/adl_serializer/index.md); +- add pure virtual functions to the [`json_sax`](../api/json_sax/index.md) interface; +- remove, rename, renumber, or add enumerators of `value_t`; +- remove or rename a documented macro, CMake option, CMake target, or header, or change what a documented macro does. Exceptions to these rules, for instance when fixing a bug requires changing the exception a function throws, are documented in the [release notes](../home/releases.md). @@ -51,13 +64,14 @@ The following are **not** part of the public API and may change in any release, - The text of exception messages returned by `what()`. Use the [exception id](../home/exceptions.md) to tell errors apart. -- The ABI, including `sizeof(basic_json)` and the memory layout of its values. Recompile your code when you upgrade the - library. The [versioned inline namespace](../features/namespace.md) turns mixing versions into a link error. +- The ABI, including `sizeof(basic_json)` and the memory layout of its values. The + [versioned inline namespace](../features/namespace.md) turns mixing versions into a link error. +- The hash values returned by `std::hash` for `basic_json`. Numbers that compare equal still hash equally. - Everything in namespace `nlohmann::detail`, and macros and type traits that are not documented in the [API reference](../api/basic_json/index.md). -Changes that would break the public API are only added behind a macro whose default keeps the 3.x behavior, see -[Version 4.0](#version-40). +Breaking changes are only added behind a macro whose default keeps the 3.x behavior. See [Version 4.0](#version-40) and +the [macro overview](../features/macros.md). ## Version 4.0 diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt index e092616b7..9318838bb 100644 --- a/tests/CMakeLists.txt +++ b/tests/CMakeLists.txt @@ -138,7 +138,8 @@ json_test_set_test_options(test-disabled_exceptions # only the #972 regression test needs thirdparty/fifo_map on its include path json_test_set_test_options(test-regression1 LINK_LIBRARIES fifo_map_include) -# GCC's false -Warray-bounds error with JSON_DIAGNOSTICS only shows up when optimizing (#5742). +# Regression test for GCC's false -Warray-bounds error with JSON_DIAGNOSTICS (#5742, fixed in #5585). It only +# showed up when optimizing, so build this test with -O3 and the warning as an error. # -O3 makes the optimizer-driven warnings of the ci_test_gcc flag set (-Winline, # -Wsuggest-attribute=...) fire on the library's inline functions; they are not # what this test checks, so turn them off for it.