From e4e7d657ef66b7809ba1ecef8f433feba3bb2652 Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Wed, 7 Oct 2026 08:49:51 +0200 Subject: [PATCH] Document the API stability guarantee in the roadmap (#5775) * Document what is not covered by the API stability guarantee Signed-off-by: Niels Lohmann * Move the API stability guarantee to the roadmap Signed-off-by: Niels Lohmann * Note that exceptions to the API stability rules are documented in the release notes Signed-off-by: Niels Lohmann --------- Signed-off-by: Niels Lohmann --- .github/CONTRIBUTING.md | 3 +++ docs/mkdocs/docs/community/roadmap.md | 30 ++++++++++++++++++++++++--- 2 files changed, 30 insertions(+), 3 deletions(-) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 6f3d0bef3..9c3bb2c04 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -205,6 +205,9 @@ API of the 3.x.y version is broken. This includes: - Changing access specifiers. - Changing default arguments. +What is and is not covered by this guarantee is described in the +[roadmap](https://json.nlohmann.me/community/roadmap/#api-stability). + Although these guidelines may seem restrictive, they are essential for maintaining the library’s utility. Breaking changes may be introduced when they are guarded with a feature macro such as diff --git a/docs/mkdocs/docs/community/roadmap.md b/docs/mkdocs/docs/community/roadmap.md index 36d5d7e7f..27afeb4c5 100644 --- a/docs/mkdocs/docs/community/roadmap.md +++ b/docs/mkdocs/docs/community/roadmap.md @@ -25,9 +25,7 @@ work items are tracked in the [GitHub milestones](https://github.com/nlohmann/js ## What the project will not do -- **Break the public API of version 3.x.** See the - [contribution guidelines](https://github.com/nlohmann/json/blob/develop/.github/CONTRIBUTING.md#break-the-public-api) - for what counts as a breaking change. +- **Break the public API of version 3.x.** See [API stability](#api-stability) for what this covers. - **Require a newer C++ standard than C++11.** - **Break JSON conformance** or enable non-standard extensions by default. - **Add dependencies** or require a build step. The library remains header-only, and the single header @@ -35,6 +33,32 @@ work items are tracked in the [GitHub milestones](https://github.com/nlohmann/js - **Trade simplicity for speed or memory efficiency.** Performance improvements are welcome, but the library is not meant to compete with the fastest JSON libraries, see [Design goals](../home/design_goals.md). +## 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: + +- 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; +- change which exceptions a function throws, or the [exception ids](../home/exceptions.md); +- change access specifiers or default arguments. + +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). + +The following are **not** part of the public API and may change in any release, including patch releases: + +- 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. +- 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). + ## Version 4.0 There is no release date for version 4.0 yet. Proposals that need a major version, for instance stricter type