diff --git a/docs/mkdocs/docs/api/macros/json_brace_init_copy_semantics.md b/docs/mkdocs/docs/api/macros/json_brace_init_copy_semantics.md index 2301a0486..e4e282607 100644 --- a/docs/mkdocs/docs/api/macros/json_brace_init_copy_semantics.md +++ b/docs/mkdocs/docs/api/macros/json_brace_init_copy_semantics.md @@ -115,3 +115,4 @@ The default value is `0` (disabled — existing behavior is preserved). ## Version history - Added in version 3.13.0. +- Planned to become the default (with the macro removed) in version 4.0.0. diff --git a/docs/mkdocs/docs/community/roadmap.md b/docs/mkdocs/docs/community/roadmap.md index e8c407d3f..c622bbbb6 100644 --- a/docs/mkdocs/docs/community/roadmap.md +++ b/docs/mkdocs/docs/community/roadmap.md @@ -14,7 +14,7 @@ work items are tracked in the [GitHub milestones](https://github.com/nlohmann/js opt-in. - **Keep the 3.x public API stable.** Releases follow [semantic versioning](https://semver.org). Changes that would break existing code are only added behind a feature macro, so users can opt in and test their code before a next - major release. + major release, see [Version 4.0](#version-40). - **Support a broad range of compilers and platforms.** The [CI](quality_assurance.md) keeps testing old and new versions of GCC, Clang, MSVC, and other compilers on Linux, macOS, and Windows. - **Keep the quality assurance up.** Every change keeps the test coverage at 100%, passes the static and dynamic @@ -37,7 +37,48 @@ work items are tracked in the [GitHub milestones](https://github.com/nlohmann/js ## Version 4.0 -There is no decision yet on whether or when a version 4.0 with breaking changes will be released. Proposals that need -a major version, for instance stricter type conversions, are collected in issue -[#3453](https://github.com/nlohmann/json/issues/3453). Until then, such changes are only added as opt-in behavior -behind feature macros. +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). + +!!! note "Not final" + + The plan for version 4.0 described below is not final and may still change: macros may be added to or removed from + the list, and planned defaults may be revised. Any such change will be documented on this page. + +### Trying out 4.0 today + +Version 4.0 will not be developed on a separate branch. Instead, every breaking change is first added to a 3.x release +behind a macro whose default keeps the 3.x behavior. Version 4.0 then switches the defaults and removes the macros. +Version 4.0 is therefore the sum of these macros: you can try it on the 3.x release train today by defining each macro +to its 4.0 value and fixing what no longer compiles or behaves differently. Once your code works with all of them, it +is ready for version 4.0. + +The following macros guard changes that are planned to become the default in version 4.0: + +| Macro | 3.x default | 4.0 behavior | CMake option | Added | +|------------------------------------------------------------------------------------------------------------------|-------------|-------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------|--------| +| [`JSON_USE_IMPLICIT_CONVERSIONS`](../api/macros/json_use_implicit_conversions.md) | `1` | `0`: no implicit conversions from `basic_json` to other types; use [`get`](../api/basic_json/get.md) instead | [`JSON_ImplicitConversions`](../integration/cmake.md#json_implicitconversions) | 3.9.0 | +| [`JSON_USE_GLOBAL_UDLS`](../api/macros/json_use_global_udls.md) | `1` | `0`: the string literals `_json` and `_json_pointer` are only available in namespace `nlohmann::literals` | [`JSON_GlobalUDLs`](../integration/cmake.md#json_globaludls) | 3.11.0 | +| [`JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON`](../api/macros/json_use_legacy_discarded_value_comparison.md) | `0` | removed: the deprecated legacy comparison of discarded values can no longer be enabled | [`JSON_LegacyDiscardedValueComparison`](../integration/cmake.md#json_legacydiscardedvaluecomparison) | 3.11.0 | +| [`JSON_BRACE_INIT_COPY_SEMANTICS`](../api/macros/json_brace_init_copy_semantics.md) | `0` | `1`: single-element brace initialization such as `#!cpp json j{obj};` copies the element instead of creating an array | – | 3.13.0 | +| [`JSON_PRECISE_STREAM_POSITION`](../api/macros/json_precise_stream_position.md) | `0` | `1`: reading from a stream does not consume the character after a number | – | 3.13.0 | +| [`JSON_STRICT_NUL_HANDLING`](../api/macros/json_strict_nul_handling.md) | `0` | `1`: a NUL byte in the input is a parse error instead of the end of input | [`JSON_StrictNulHandling`](../integration/cmake.md#json_strictnulhandling) | 3.13.0 | + +For example, the following makes a 3.x release behave like version 4.0 with respect to these changes: + +```cpp +#define JSON_USE_IMPLICIT_CONVERSIONS 0 +#define JSON_USE_GLOBAL_UDLS 0 +#define JSON_BRACE_INIT_COPY_SEMANTICS 1 +#define JSON_PRECISE_STREAM_POSITION 1 +#define JSON_STRICT_NUL_HANDLING 1 +#include +``` + +The macros must be defined before the library header is included; setting them once in the build system is the easiest +way to achieve this. In addition, +version 4.0 will remove all [deprecated functions](../integration/migration_guide.md#replace-deprecated-functions). +Compiling with deprecation warnings enabled shows which of them your code still uses. The +[migration guide](../integration/migration_guide.md) describes how to replace them. + +New breaking changes will follow the same path: they are added to this table when they land in a 3.x release. diff --git a/docs/mkdocs/docs/integration/migration_guide.md b/docs/mkdocs/docs/integration/migration_guide.md index 8b718d969..22dacf70a 100644 --- a/docs/mkdocs/docs/integration/migration_guide.md +++ b/docs/mkdocs/docs/integration/migration_guide.md @@ -1,6 +1,8 @@ # Migration Guide This page collects some guidelines on how to future-proof your code for future versions of this library. +The [roadmap](../community/roadmap.md#trying-out-40-today) lists all macros that let you try the behavior of version +4.0 with a 3.x release. ## Replace deprecated functions