Repository navigation
Document the API stability guarantee in the roadmap - #5775
Merged
Merged
Conversation
Signed-off-by: Niels Lohmann <mail@nlohmann.me>
Signed-off-by: Niels Lohmann <mail@nlohmann.me>
nlohmann
changed the title
… release notes Signed-off-by: Niels Lohmann <mail@nlohmann.me>
gregmarr
approved these changes
Oct 7, 2026
| 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: | ||
|
|
||
| - change the signature of a function (its parameter types, return type, number of parameters, or the const-ness of a |
Contributor
There was a problem hiding this comment.
This is too strict. New parameters may be added if they are defaulted.
Owner
Author
| member function); | ||
| - remove or rename a function or class; | ||
| - change which exceptions a function throws, or the [exception ids](../home/exceptions.md); | ||
| - change access specifiers or default arguments. |
Contributor
There was a problem hiding this comment.
It may add new defaults but not change existing ones.
Owner
Author
| ## 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: |
Contributor
There was a problem hiding this comment.
Clarification?
does not break code that uses the public API
without a macro opt-in as described below
Owner
Author
|
|
||
| - 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 |
Contributor
There was a problem hiding this comment.
Recompile your code when you upgrade the library
That's a given because it's header-only, and different releases are not interoperable due to the versioning namespace as described in the next sentence.
Owner
Author
nlohmann
added a commit
that referenced
this pull request
Oct 8, 2026
…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 <mail@nlohmann.me> * 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 <mail@nlohmann.me> --------- Signed-off-by: Niels Lohmann <mail@nlohmann.me>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Users had no single place to look up what the 3.x API guarantee covers. The roadmap only said that releases follow semantic versioning, and the details were in the contribution guidelines, written as rules for contributors. Nothing said what is not covered, so users had to guess about exception message texts,
sizeof(json), ornlohmann::detail(see discussion #3473).This adds an API stability section to the roadmap:
what());sizeof(basic_json)and the memory layout, with a link to the versioned inline namespace;nlohmann::detail, and macros and type traits not documented in the API reference.The roadmap's "Break the public API" item now links to this section. The "Break the public API" section of
CONTRIBUTING.mdkeeps its rules for contributors and links to the roadmap for the guarantee.API impact
No breaking changes. This is documentation only, and it describes existing practice: for example, exception messages have been improved in past releases.
Written by Claude Code.
🤖 Generated with Claude Code