docs: add a supported versions page

AGENTS.md

@@ -100,6 +100,7 @@ Packaging produces two distributions: the normal `pybind11` (headers live inside
   introduces or broadens a path that can discard or replace the primary error,
   flag it to the human reviewer and explain whether the policy's exceptional-case
   allowance is justified.
+- If you change a minimum supported version (headers, CMake, `pyproject.toml`, or the CI matrix), update `docs/supported.rst`.
 - Try to add to an existing test file if possible (more files slow down tests).
 - Default C++ standard follows the consumer's toolchain; CI exercises a wide matrix (CPython 3.9+, PyPy, GraalPy; multiple compilers and C++ standards). Keep changes portable across that matrix.
 - PR descriptions follow a template, the key part is under "Suggested changelog entry", which is how we generate our changelog (with `nox -s make_changelog`)

README.rst

@@ -124,7 +124,9 @@ Supported platforms & compilers
 -------------------------------
 
 pybind11 is exercised in continuous integration across a range of operating
-systems, Python versions, C++ standards, and toolchains. For an up-to-date
+systems, Python versions, C++ standards, and toolchains. The
+`supported versions <https://pybind11.readthedocs.io/en/latest/supported.html>`_
+page lists the minimum version of each one. For an up-to-date
 view of the combinations we currently test, please see the
 `pybind11 GitHub Actions <https://github.com/pybind/pybind11/actions?query=branch%3Amaster>`_
 and `AppVeyor <https://ci.appveyor.com/project/wjakob/pybind11>`_ logs.

docs/index.rst

@@ -20,6 +20,7 @@
    :maxdepth: 2
 
    installing
+   supported
    basics
    classes
    compiling

docs/supported.rst

@@ -0,0 +1,129 @@
+.. _supported:
+
+Supported versions
+##################
+
+This page lists the oldest version of each tool or dependency that pybind11
+supports. Each entry has two values:
+
+**Minimum expected**
+    The oldest version that we intend to work. Usually the headers or the build
+    system reject older versions with an error. We fix bugs reported for these
+    versions, but CI does not always test them.
+
+**Minimum tested**
+    The oldest version that CI tests. Versions between the two minimums
+    usually work, but we do not test them.
+
+When you change one of these minimums (in the headers, in CMake, in
+``pyproject.toml``, or in the CI matrix), update this table too.
+
+Python
+======
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 20 20 30
+
+   * - Implementation
+     - Minimum expected
+     - Minimum tested
+     - Notes
+   * - CPython
+     - 3.9
+     - 3.9
+     -
+   * - CPython, free-threaded
+     - 3.13t
+     - 3.14t
+     - See :ref:`misc_free_threading`.
+   * - CPython, stable ABI (``abi3``)
+     - 3.12
+     - 3.12
+     - See :doc:`advanced/stable_abi`.
+   * - CPython, free-threaded stable ABI (``abi3t``)
+     - 3.15t
+     - 3.15t
+     -
+   * - PyPy
+     - 3.10
+     - 3.11 (v7.3.23)
+     -
+   * - GraalPy
+     - 25.0
+     - 25.0
+     -
+
+We plan to drop 3.13t support soon, as it was experimental. Use 3.14t or newer.
+
+C++ standard and compilers
+==========================
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 20 20 30
+
+   * - Compiler
+     - Minimum expected
+     - Minimum tested
+     - Notes
+   * - C++ standard
+     - C++11
+     - C++11
+     - CI tests C++11 through C++23.
+   * - GCC
+     - 4.8
+     - 8 (AlmaLinux 8)
+     -
+   * - Clang
+     - 3.3
+     - 5
+     -
+   * - Apple Clang
+     - Xcode 5
+     - Xcode 16
+     - The version of the default macOS runner.
+   * - MSVC
+     - 2019 (19.20)
+     - 2022
+     - GitHub Actions does not have MSVC 2019 runners.
+   * - Intel ICC (classic)
+     - 18 (C++11), 19 (C++14)
+     - Latest classic ICC
+     -
+   * - NVCC (CUDA)
+     -
+     - 12.2
+     -
+   * - NVIDIA HPC SDK
+     -
+     - 26.5
+     -
+
+Build tools and optional dependencies
+=====================================
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 20 20 30
+
+   * - Tool
+     - Minimum expected
+     - Minimum tested
+     - Notes
+   * - CMake
+     - 3.15
+     - 3.15
+     - The newest tested version is 4.2.
+   * - Eigen
+     - 3.2.7
+     - 3.3.9
+     - ``pybind11/eigen/tensor.h`` needs Eigen 3.3.0 or newer.
+   * - NumPy
+     -
+     - 1.21
+     - NumPy 2 needs pybind11 2.12 or newer.
+   * - scikit-build-core
+     - 0.11.2
+     - latest
+     - Only needed to build the pybind11 Python package from source.