Skip to content

Document what counts as a breaking change in the API stability rules - #5785

Closed
nlohmann wants to merge 1 commit into
developfrom
docs/api-stability-rules
Closed

nlohmann wants to merge 1 commit into
developfrom
docs/api-stability-rules

Conversation

@nlohmann

@nlohmann nlohmann commented Oct 8, 2026 •

Copy link
Copy Markdown
Owner

Follow-up to #5784, addressing gregmarr's review there. Starts from develop.

  • Reword the first bullet to "make breaking changes to the signature of a function", as suggested in the review.
  • Allow new defaulted parameters and new default arguments in 3.x.
  • List more things that break users: 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.
  • List std::hash values as not part of the public API.
  • Link the macro overview and Version 4.0 from the section.

API compatibility

Docs only. No public API change: no code, headers, or build files are touched. The change describes the existing 3.x rules more precisely, and it adds std::hash values to the "not part of the public API" list, which matches #5772.

🤖 Generated with Claude Code

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>
@nlohmann

nlohmann commented Oct 8, 2026

Copy link
Copy Markdown
Owner Author

Closing: the roadmap changes move into #5784 instead.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant