From 00c1c0e274da8927dfd231ec43b431d58d3a95ce Mon Sep 17 00:00:00 2001
From: Niels Lohmann <mail@nlohmann.me>
Date: Thu, 24 Sep 2026 17:31:58 +0200
Subject: [PATCH] Add a roadmap page to the documentation

Describe what the project will and will not do over the next year,
and point to issue #3453 for the open question of a 4.0 release.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>
---
 docs/mkdocs/docs/community/index.md   |  1 +
 docs/mkdocs/docs/community/roadmap.md | 43 +++++++++++++++++++++++++++
 docs/mkdocs/mkdocs.yml                |  1 +
 3 files changed, 45 insertions(+)
 create mode 100644 docs/mkdocs/docs/community/roadmap.md

diff --git a/docs/mkdocs/docs/community/index.md b/docs/mkdocs/docs/community/index.md
index 50baeab25..c7d0cf079 100644
--- a/docs/mkdocs/docs/community/index.md
+++ b/docs/mkdocs/docs/community/index.md
@@ -5,4 +5,5 @@
 - [Contribution Guidelines](contribution_guidelines.md) - guidelines how to contribute to this project
 - [Governance](governance.md) - the governance model of this project
 - [Quality Assurance](quality_assurance.md) - how the quality of this project is assured
+- [Roadmap](roadmap.md) - what the project will and will not do
 - [Security Policy](security_policy.md) - the security policy of the project
diff --git a/docs/mkdocs/docs/community/roadmap.md b/docs/mkdocs/docs/community/roadmap.md
new file mode 100644
index 000000000..e8c407d3f
--- /dev/null
+++ b/docs/mkdocs/docs/community/roadmap.md
@@ -0,0 +1,43 @@
+# Roadmap
+
+This page describes what the project intends to do, and what it does not intend to do, over the next year. Concrete
+work items are tracked in the [GitHub milestones](https://github.com/nlohmann/json/milestones) and the
+[issue tracker](https://github.com/nlohmann/json/issues).
+
+## What the project will do
+
+- **Keep the C++11 baseline.** The library will continue to compile with every
+  [supported C++11 compiler](https://github.com/nlohmann/json/blob/develop/README.md#supported-compilers). Features of
+  later standards are only used when they are guarded by the `JSON_HAS_CPP_*` macros.
+- **Stay conformant to JSON.** The parser and serializer follow [RFC 8259](https://datatracker.ietf.org/doc/html/rfc8259).
+  Extensions such as [comments](../features/comments.md) or [trailing commas](../features/trailing_commas.md) remain
+  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.
+- **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
+  analysis, and is fuzz-tested by OSS-Fuzz, see [Quality assurance](quality_assurance.md).
+- **Harden the library against hostile input.** Handling deeply nested values without exhausting the call stack is
+  ongoing work.
+- **Fix bugs and security issues** reported through the issue tracker and the [security policy](security_policy.md).
+
+## 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.
+- **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](../home/design_goals.md).
+
+## 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.
diff --git a/docs/mkdocs/mkdocs.yml b/docs/mkdocs/mkdocs.yml
index 8f92a838f..9400222b1 100644
--- a/docs/mkdocs/mkdocs.yml
+++ b/docs/mkdocs/mkdocs.yml
@@ -317,6 +317,7 @@ nav:
       - community/contribution_guidelines.md
       - community/quality_assurance.md
       - community/governance.md
+      - community/roadmap.md
       - community/security_policy.md
 
 # Extras