deploy: e4e7d657ef

community/roadmap/index.md

@@ -14,12 +14,31 @@ This page describes what the project intends to do, and what it does not intend
 
 ## 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 `json.hpp` remains a complete distribution.
 - **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](https://json.nlohmann.me/home/design_goals/index.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](https://json.nlohmann.me/home/exceptions/index.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](https://json.nlohmann.me/home/releases/index.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](https://json.nlohmann.me/home/exceptions/index.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](https://json.nlohmann.me/features/namespace/index.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](https://json.nlohmann.me/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 conversions, are collected in issue [#3453](https://github.com/nlohmann/json/issues/3453).