docs: prepare for v3.0.0rc1 (#5589)

* Squashed prepv300/manuscript — 30b9c268aeb98308ea42aaccfd5fe454e173c6fc — 2025-03-30 14:56:03 -0700 [skip ci]

[Browse prepv300/manuscript tree](30b9c268ae)

[Browse prepv300/manuscript commits](30b9c268ae/)

* docs: update changelog

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>

* docs: upgrade guide CMake suggestions

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>

* Explain type_caster_enum_type_enabled, copyable_holder_caster_shared_ptr_with_smart_holder_support_enabled, move_only_holder_caster_unique_ptr_with_smart_holder_support_enabled in Upgrade guide.

* Add a small section for py::bind_vector, py::bind_map & py::smart_holder

* Fix tiny oversight: Reference back to the current release v2.13 (not v2.12)

* Remove sentence: Using self._pybind11_conduit_v1_() ... should keep extension compatibility.

This isn't true, because we also modernized `PYBIND11_PLATFORM_ABI_ID`
(which I believe was absolutely necessary). I think it'll be too complicated
to explain that here, and there is a mention in the Upgrade guide.

* Changelog: combine #4953 and #5439

* Trivial whitespace/formatting fixes/enhancements.

* chore: add more to deprecation page

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>

* docs: update for recent additions

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>

* docs: fixes and set rc1 version

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>

* fix: support rc versions

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>

* Undo erroneous copilot change: We need to use `detail::enable_if_t`, for compatibility with C++11 and C++14.

* Empty lines cleanup.

* Rewording of "CMake support now defaults to ..." paragraph.

* Add missing backticks in upgrade guide.

* Try :ref:deprecated instead of :doc:deprecated

* docs: last bit of polish

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>

* Piggy-back trivial whitespace cleanup that was missed in PR #5669

---------

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>
Co-authored-by: Henry Schreiner <henryschreineriii@gmail.com>

docs/advanced/classes.rst

@@ -1384,7 +1384,7 @@ You can do that using ``py::custom_type_setup``:
            auto *type = &heap_type->ht_type;
            type->tp_flags |= Py_TPFLAGS_HAVE_GC;
            type->tp_traverse = [](PyObject *self_base, visitproc visit, void *arg) {
-               // https://docs.python.org/3/c-api/typeobj.html#c.PyTypeObject.tp_traverse
+   // https://docs.python.org/3/c-api/typeobj.html#c.PyTypeObject.tp_traverse
    #if PY_VERSION_HEX >= 0x03090000
                Py_VISIT(Py_TYPE(self_base));
    #endif

docs/advanced/deprecated.rst

@@ -1,6 +1,72 @@
+.. _deprecated:
+
 Deprecated
 ##########
 
+Support for Python 3.8 is deprecated and will be removed in 3.1.
+
+Support for C++11 is deprecated and will be removed in a future version. Please
+use at least C++14.
+
+Support for FindPythonLibs (not available in CMake 3.26+ mode) is deprecated
+and will be removed in a future version. The default mode is also going to
+change to ``"new"`` from ``"compat"`` in the future.
+
+The following features were deprecated before pybind11 3.0, and may be removed
+in minor releases of pybind11 3.x.
+
+.. list-table:: Deprecated Features
+   :header-rows: 1
+   :widths: 30 15 10
+
+   * - Feature
+     - Deprecated Version
+     - Year
+   * - ``py::metaclass()``
+     - 2.1
+     - 2017
+   * - ``PYBIND11_PLUGIN``
+     - 2.2
+     - 2017
+   * - ``py::set_error()`` replacing ``operator()``
+     - 2.12
+     - 2024
+   * - ``get_type_overload``
+     - 2.6
+     - 2020
+   * - ``call()``
+     - 2.0
+     - 2016
+   * - ``.str()``
+     - ?
+     -
+   * - ``.get_type()``
+     - 2.6
+     -
+   * - ``==`` and ``!=``
+     - 2.2
+     - 2017
+   * - ``.check()``
+     - ?
+     -
+   * - ``object(handle, bool)``
+     - ?
+     -
+   * - ``error_already_set.clear()``
+     - 2.2
+     - 2017
+   * - ``obj.attr(…)`` as ``bool``
+     - ?
+     -
+   * - ``.contains``
+     - ? (maybe 2.4)
+     -
+   * - ``py::capsule`` two-argument with destructor
+     - ?
+     -
+
+
+
 .. _deprecated_enum:
 
 ``py::enum_``

docs/changelog.rst

@@ -10,29 +10,312 @@ Changes will be added here periodically from the "Suggested changelog entry"
 block in pull request descriptions.
 
 
-IN DEVELOPMENT
+3.0.0 RC 1
---------------
+----------
 
-Changes will be summarized here periodically.
+We may add one more opt-in feature (embedded subinterperters) before the final
+release.
 
 New Features:
 
-* Support for Python 3.7 was removed. (Official end-of-life: 2023-06-27).
+* The ``smart-holder`` branch has been merged, enabling ``py::class_<T,
-  `#5191 <https://github.com/pybind/pybind11/pull/5191>`_
+  py::smart_holder>``, which handles two-way conversion with
+  ``std::unique_ptr<T>`` and ``std::shared_ptr<T>`` (simultaneously), disowning
+  a Python object being passed to ``std::unique_ptr<T>``, trampoline objects,
+  and ``std::enable_shared_from_this``.
+  `#5542 <https://github.com/pybind/pybind11/pull/5542>`_
+
+* Changed ``PYBIND11_MODULE`` macro implementation to perform multi-phase
+  module initialization (PEP 489) behind the scenes.
+  `#5574 <https://github.com/pybind/pybind11/pull/5574>`_
+
+* Support for sub-interpreters (both isolated (with separate GILs) and legacy
+  (with a global GIL). Add the
+  ``py::multiple_interpreters::per_interpreter_gil()`` tag (or,
+  ``py::multiple_interpreters::shared_gil()`` for legacy interpreter support)
+  to ``PYBIND11_MODULE`` calls (as the third parameter) to indicate that a
+  module supports running with sub-interpreters.
+  `#5564 <https://github.com/pybind/pybind11/pull/5564>`_
+
+* Changed ``PYBIND11_EMBEDDED_MODULE`` macro implementation to perform
+  multi-phase module initialization (PEP 489) behind the scenes and to support
+  ``py::mod_gil_not_used()``, ``py::multiple_interpreters::per_interpreter_gil()``
+  and ``py::multiple_interpreters::shared_gil()``.
+  `#5665 <https://github.com/pybind/pybind11/pull/5665>`_
+
+* ``py::native_enum`` was added, for conversions between Python's native (stdlib) enum types and C++ enums.
+  `#5555 <https://github.com/pybind/pybind11/pull/5555>`_
+
+  * Add class doc string to ``py::native_enum``.
+  `#5617 <https://github.com/pybind/pybind11/pull/5617>`_.
+
+  * Fix signature for functions with a native_enum in the signature.
+  `#5619 <https://github.com/pybind/pybind11/pull/5619>`_
+
+* A ``py::release_gil_before_calling_cpp_dtor`` option (for ``py::class_``) was
+  added to resolve the long-standing issue #1446.
+  `#5522 <https://github.com/pybind/pybind11/pull/5522>`_
+
+* Add ``dtype::normalized_num`` and ``dtype::num_of``.
+  `#5429 <https://github.com/pybind/pybind11/pull/5429>`_
+
+* Add support for ``array_t<handle>`` and ``array_t<object>``.
+  `#5427 <https://github.com/pybind/pybind11/pull/5427>`_
+
+* Added ``py::warnings`` namespace with ``py::warnings::warn`` and
+  ``py::warnings::new_warning_type`` that provides the interface for Python
+  warnings.
+  `#5291 <https://github.com/pybind/pybind11/pull/5291>`_
 
 * stl.h ``list|set|map_caster`` were made more user friendly: it is no longer
   necessary to explicitly convert Python iterables to ``tuple()``, ``set()``,
   or ``map()`` in many common situations.
   `#4686 <https://github.com/pybind/pybind11/pull/4686>`_
 
-* Support for CMake older than 3.15 removed. CMake 3.15-3.30 supported.
-  `#5304 <https://github.com/pybind/pybind11/pull/5304>`_
-
 * The ``array_caster`` in pybind11/stl.h was enhanced to support value types that are not default-constructible.
   `#5305 <https://github.com/pybind/pybind11/pull/5305>`_
 
-* Added ``py::warnings`` namespace with ``py::warnings::warn`` and ``py::warnings::new_warning_type`` that provides the interface for Python warnings.
+* ``pybind11/conduit/pybind11_platform_abi_id.h`` was factored out, to maximize
-  `#5291 <https://github.com/pybind/pybind11/pull/5291>`_
+  reusability of ``PYBIND11_PLATFORM_ABI_ID`` (for other Python/C++ binding
+  systems).
+  `#5375 <https://github.com/pybind/pybind11/pull/5375>`_
+
+* Added support for finding pybind11 using pkgconf distributed on pypi.
+  `#5552 <https://github.com/pybind/pybind11/pull/5552>`_
+
+* Support ``--extension-suffix`` on the pybind11 command.
+  `#5360 <https://github.com/pybind/pybind11/pull/5360>`_
+
+* Add semi-public API: ``pybind11::detail::is_holder_constructed`` and update
+  example for ``pybind11::custom_type_setup`` in documentation.
+  `#5669 <https://github.com/pybind/pybind11/pull/5669>`_
+
+
+New Features (typing):
+
+* Added option for different arg/return type hints to ``type_caster``. Updated
+  ``stl/filesystem`` to use correct arg/return type hints. Updated
+  ``pybind11::typing`` to use correct arg/return type hints for nested types.
+  `#5450 <https://github.com/pybind/pybind11/pull/5450>`_
+
+* Updated type hint for ``py::capsule`` to ``type.CapsuleType``.
+  `#5567 <https://github.com/pybind/pybind11/pull/5567>`_
+
+* Adds support for ``typing.SupportsInt`` and ``typing.SupportsFloat``.
+  Update ``Final`` to be narrower type hint. Make ``std::function`` match
+  ``Callable`` type. Fix ``io_name`` bug in ``attr_with_type_hint``.
+  `#5540 <https://github.com/pybind/pybind11/pull/5540>`_
+
+* Rework of arg/return type hints to support ``.noconvert()``.
+  `#5486 <https://github.com/pybind/pybind11/pull/5486>`_
+
+* Add ``attr_with_type`` for declaring attribute types and ``Final``, ``ClassVar`` type annotations.
+  `#5460 <https://github.com/pybind/pybind11/pull/5460>`_
+
+* Allow annotate methods with ``py::pos_only`` when only have the ``self``
+  argument. Make arguments for auto-generated dunder methods positional-only.
+  `#5403 <https://github.com/pybind/pybind11/pull/5403>`_
+
+* Added ``py::Args`` and ``py::KWArgs`` to enable custom type hinting of ``*args`` and ``**kwargs`` (see PEP 484).
+  `#5357 <https://github.com/pybind/pybind11/pull/5357>`_
+
+* Switched to ``numpy.typing.NDArray`` and ``numpy.typing.ArrayLike``.
+  `#5212 <https://github.com/pybind/pybind11/pull/5212>`_
+
+.. fix(types)
+
+* Use ``numpy.object_`` instead of ``object``.
+  `#5571 <https://github.com/pybind/pybind11/pull/5571>`_
+
+* Fix module type hint.
+  `#5469 <https://github.com/pybind/pybind11/pull/5469>`_
+
+* Fix Buffer type hint.
+  `#5662 <https://github.com/pybind/pybind11/pull/5662>`_
+
+* Added support for ``collections.abc`` in type hints and convertible checks of STL casters and ``py::buffer``.
+  `#5566 <https://github.com/pybind/pybind11/pull/5566>`_
+
+
+Removals:
+
+* Remove support for pybind11 v2 internals versions (4, 5, 6).
+  (The internals version number has been bumped for pybind11 v3.)
+  `#5512 <https://github.com/pybind/pybind11/pull/5512>`_ |
+  `#5530 <https://github.com/pybind/pybind11/pull/5530>`_
+
+* Remove ``make_simple_namespace`` (added in 2.8.0, deprecated in 2.8.1).
+  `#5597 <https://github.com/pybind/pybind11/pull/5597>`_
+
+* Legacy-mode option ``PYBIND11_NUMPY_1_ONLY`` has been removed.
+  `#5595 <https://github.com/pybind/pybind11/pull/5595>`_
+
+* Add a deprecation warning to ``.get_type`` (deprecated in pybind11 2.6 in 2020).
+  `#5596 <https://github.com/pybind/pybind11/pull/5596>`_
+
+
+Bug fixes:
+
+* Set ``__file__`` on submodules.
+  `#5584 <https://github.com/pybind/pybind11/pull/5584>`_. Except on embedded modules. `#5650 <https://github.com/pybind/pybind11/pull/5650>`_
+
+* pybind11-bound functions are now pickleable.
+  `#5580 <https://github.com/pybind/pybind11/pull/5580>`_
+
+* Fix bug in ``attr_with_type_hint`` to allow objects to be in ``attr_with_type_hint``.
+  `#5576 <https://github.com/pybind/pybind11/pull/5576>`_
+
+* A ``-Wmaybe-uninitialized`` warning suppression was added in ``pybind11/eigen/matrix.h``.
+  `#5516 <https://github.com/pybind/pybind11/pull/5516>`_
+
+* ``PYBIND11_WARNING_POP`` was incorrectly defined as ``PYBIND11_PRAGMA(clang diagnostic push)``.
+  `#5448 <https://github.com/pybind/pybind11/pull/5448>`_
+
+* ``PYBIND11_PLATFORM_ABI_ID`` (which is used in composing ``PYBIND11_INTERNALS_ID``) was modernized to reflect actual ABI compatibility more accurately.
+  `#4953 <https://github.com/pybind/pybind11/pull/4953>`_ |
+  `#5439 <https://github.com/pybind/pybind11/pull/5439>`_
+
+* Fix buffer protocol implementation.
+  `#5407 <https://github.com/pybind/pybind11/pull/5407>`_
+
+* Fix iterator increment operator does not skip first item.
+  `#5400 <https://github.com/pybind/pybind11/pull/5400>`_
+
+* When getting or deleting an element in a container bound by ``bind_map``, print the key in ``KeyError`` if it does not exist.
+  `#5397 <https://github.com/pybind/pybind11/pull/5397>`_
+
+* ``pybind11::builtin_exception`` is now explicitly exported when linked to libc++.
+  `#5390 <https://github.com/pybind/pybind11/pull/5390>`_
+
+* Allow subclasses of ``py::args`` and ``py::kwargs``.
+  `#5381 <https://github.com/pybind/pybind11/pull/5381>`_
+
+* Disable false-positive GCC 12 Bound Check warning.
+  `#5355 <https://github.com/pybind/pybind11/pull/5355>`_
+
+* fix: using ``__cpp_nontype_template_args`` instead of ``__cpp_nontype_template_parameter_class``.
+  `#5330 <https://github.com/pybind/pybind11/pull/5330>`_
+
+* Properly translate C++ exception to Python exception when creating Python buffer from wrapped object.
+  `#5324 <https://github.com/pybind/pybind11/pull/5324>`_
+
+* Update the dict when restoring pickles, instead of assigning a replacement dict.
+  `#5658 <https://github.com/pybind/pybind11/pull/5658>`_
+
+* Properly define ``_DEBUG`` macro to ``1`` instead of defining it without value.
+  `#5639 <https://github.com/pybind/pybind11/pull/5639>`_
+
+* Fix a missing time cast causing a compile error for newer ICC.
+  `#5621 <https://github.com/pybind/pybind11/pull/5621>`_
+
+* Change the behavior of the default constructor of ``py::slice`` to be equivalent to ``::`` in Python.
+  `#5620 <https://github.com/pybind/pybind11/pull/5620>`_
+
+
+Bug fixes (CMake):
+
+* (CMake) Enable FindPython mode by default, with a ``COMPAT`` mode that sets
+  some of the old variables to ease transition.
+  `#5553 <https://github.com/pybind/pybind11/pull/5553>`_
+
+* Add an author warning that auto-calculated ``PYTHON_MODULE_EXTENSION`` may not respect ``SETUPTOOLS_EXT_SUFFIX`` during cross-compilation.
+  `#5495 <https://github.com/pybind/pybind11/pull/5495>`_
+
+* Don't strip with ``CMAKE_BUILD_TYPE`` None.
+  `#5392 <https://github.com/pybind/pybind11/pull/5392>`_
+
+* Fix an issue with ``NO_EXTRAS`` adding ``pybind11::windows_extras`` anyway.
+  `#5378 <https://github.com/pybind/pybind11/pull/5378>`_
+
+* Fix issue with NEW/OLD message showing up.
+  `#5656 <https://github.com/pybind/pybind11/pull/5656>`_
+
+* Use CMake's warnings as errors if available (CMake 3.24+).
+  `#5612 <https://github.com/pybind/pybind11/pull/5612>`_
+
+* Add support for running pybind11's tests via presets in CMake 3.25+.
+  `#5655 <https://github.com/pybind/pybind11/pull/5655>`_
+
+* Restructure venv support to support ``--fresh``, make in build folder.
+  `#5668 <https://github.com/pybind/pybind11/pull/5668>`_
+
+
+Bug fixes (free-threading):
+
+* Fix data race in free threaded CPython when accessing a shared static variable.
+  `#5494 <https://github.com/pybind/pybind11/pull/5494>`_
+
+* A free-threading data race in ``all_type_info()`` was fixed.
+  `#5419 <https://github.com/pybind/pybind11/pull/5419>`_
+
+* Added exception translator specific mutex used with ``try_translate_exceptions`` in the free-threaded build for internal locking.
+  `#5362 <https://github.com/pybind/pybind11/pull/5362>`_
+
+
+Internals:
+
+* Consolidated all ``PYBIND11_HAS_...`` feature macros into ``pybind11/detail/common.h`` to streamline backward compatibility checks and simplify internal refactoring. This change ensures
+consistent macro availability regardless of header inclusion order.
+  `#5647 <https://github.com/pybind/pybind11/pull/5647>`_
+
+* ``pybind11/gil_simple.h`` was factored out from ``pybind11/gil.h``, so that it can easily be reused.
+  `#5614 <https://github.com/pybind/pybind11/pull/5614>`_
+
+
+Documentation:
+
+* Improved ``reference_internal`` policy documentation.
+  `#5528 <https://github.com/pybind/pybind11/pull/5528>`_
+
+* A new "Double locking, deadlocking, GIL" document was added.
+  `#5394 <https://github.com/pybind/pybind11/pull/5394>`_
+
+* Adds an answer (FAQ) for "What is a highly conclusive and simple way to find memory leaks?".
+  `#5340 <https://github.com/pybind/pybind11/pull/5340>`_
+
+* Add documenting for free-threading and subinterpreters.
+  `#5659 <https://github.com/pybind/pybind11/pull/5659>`_
+
+
+Tests:
+
+* Download the final Catch2 2.x release if Catch download is requested.
+  `#5568 <https://github.com/pybind/pybind11/pull/5568>`_
+
+* Explicitly used ``signed char`` for two numpy dtype tests. As seen when
+compiling using ``clang`` on Linux with the ``-funsigned-char`` flag.
+  `#5545 <https://github.com/pybind/pybind11/pull/5545>`_
+
+* Test PyPy3.11 in CI.
+  `#5534 <https://github.com/pybind/pybind11/pull/5534>`_
+
+* CI testing now includes ``-Wwrite-strings -Wunreachable-code -Wpointer-arith -Wredundant-decls`` in some jobs.
+  `#5523 <https://github.com/pybind/pybind11/pull/5523>`_
+
+
+New and removed platforms:
+
+* Support Python 3.14 (beta 1).
+  `#5646 <https://github.com/pybind/pybind11/pull/5646>`_
+
+* Added support for GraalPy Python implementation (https://github.com/oracle/graalpython).
+  `#5380 <https://github.com/pybind/pybind11/pull/5380>`_
+
+* Support for PyPy 3.11 added.
+  `#5508 <https://github.com/pybind/pybind11/pull/5508>`_
+
+* Support for PyPy 3.8 and 3.9 was dropped.
+  `#5578 <https://github.com/pybind/pybind11/pull/5578>`_
+
+* Support for Python 3.7 was removed. (Official end-of-life: 2023-06-27).
+  `#5191 <https://github.com/pybind/pybind11/pull/5191>`_
+
+* Support for CMake older than 3.15 removed. CMake 3.15-4.0 supported.
+  `#5304 <https://github.com/pybind/pybind11/pull/5304>`_
+
+* Use scikit-build-core for the build backend for the PyPI ``pybind11``. The CMake generation has been moved to the sdist->wheel step. ``PYBIND11_GLOBAL_PREFIX`` has been removed.
+  `#5598 <https://github.com/pybind/pybind11/pull/5598>`_
+
 
 Version 2.13.6 (September 13, 2024)
 -----------------------------------

docs/classes.rst

@@ -642,7 +642,7 @@ As of Python 3.13, the compatible `types in the stdlib enum module
         template <typename FancyEnum>
         struct type_caster_enum_type_enabled<
             FancyEnum,
-            std::enable_if_t<is_fancy_enum<FancyEnum>::value>> : std::false_type {};
+            enable_if_t<is_fancy_enum<FancyEnum>::value>> : std::false_type {};
         }
         #endif
 

docs/upgrade.rst

@@ -8,6 +8,157 @@ to a new version. But it goes into more detail. This includes things like
 deprecated APIs and their replacements, build system changes, general code
 modernization and other useful information.
 
+.. _upgrade-guide-3.0:
+
+v3.0
+====
+
+pybind11 v3.0 introduces major new features, but the vast majority of
+existing extensions are expected to build and run without modification. Minor
+adjustments may be needed in rare cases, and any such changes can be easily
+wrapped in preprocessor conditionals to maintain compatibility with the
+2.x series.
+
+However, due to new features and modernizations, extensions built with
+pybind11 v3.0 are not ABI-compatible with those built using v2.13. To ensure
+cross-extension-module compatibility, it is recommended to rebuild all
+pybind11-based extensions with v3.0.
+
+CMake support now defaults to the modern FindPython module. If you haven't
+updated yet, we provide some backward compatibility for ``PYTHON_*`` variables,
+but you should switch to using ``Python_*`` variables instead. Note that
+setting ``PYTHON_*`` variables no longer affects the build.
+
+A major new feature in this release is the integration of
+``py::smart_holder``, which improves support for ``std::unique_ptr``
+and ``std::shared_ptr``, resolving several long-standing issues. See
+:ref:`smart_holder` for details. Closely related is the addition
+of ``py::trampoline_self_life_support``, documented under
+:ref:`overriding_virtuals`.
+
+This release includes a major modernization of cross-extension-module
+ABI compatibility handling. The new implementation reflects actual ABI
+compatibility much more accurately than in previous versions. The details
+are subtle and complex; see
+`#4953 <https://github.com/pybind/pybind11/pull/4953>`_ and
+`#5439 <https://github.com/pybind/pybind11/pull/5439>`_.
+
+Also new in v3.0 is ``py::native_enum``, a modern API for exposing
+C++ enumerations as native Python types — typically standard-library
+``enum.Enum`` or related subclasses. This provides improved integration with
+Python's enum system, compared to the older (now deprecated) ``py::enum_``.
+See `#5555 <https://github.com/pybind/pybind11/pull/5555>`_ for details.
+
+Functions exposed with pybind11 are now pickleable. This removes a
+long-standing obstacle when using pybind11-bound functions with Python features
+that rely on pickling, such as multiprocessing and caching tools.
+See `#5580 <https://github.com/pybind/pybind11/pull/5580>`_ for details.
+
+Anything producing a deprecation warning in the 2.x series may be removed in a
+future minor release of 3.x. Most of these are still present in 3.0 in order to ease
+transition. The new :ref:`deprecated` page details deprecations.
+
+Migration Recommendations
+-------------------------
+
+We recommend migrating to pybind11 v3.0 promptly, while keeping initial
+changes to a minimum. Most projects can upgrade simply by updating the
+pybind11 version, without altering existing binding code.
+
+After a short stabilization period — enough to surface any subtle issues —
+you may incrementally adopt new features where appropriate:
+
+* Use ``py::smart_holder`` and ``py::trampoline_self_life_support`` as needed,
+  or to improve code health. Note that ``py::classh`` is available as a
+  shortcut — for example, ``py::classh<Pet>`` is shorthand for
+  ``py::class_<Pet, py::smart_holder>``. This is designed to enable easy
+  experimentation with ``py::smart_holder`` without introducing distracting
+  whitespace changes. In many cases, a global replacement of ``py::class_``
+  with ``py::classh`` can be an effective first step. Build failures will
+  quickly identify places where ``std::shared_ptr<...>`` holders need to be
+  removed. Runtime failures (assuming good unit test coverage) will highlight
+  base-and-derived class situations that require coordinated changes.
+
+  Note that ``py::bind_vector`` and ``py::bind_map`` (in pybind11/stl_bind.h)
+  have a ``holder_type`` template parameter that defaults to
+  ``std::unique_ptr``. If ``py::smart_holder`` functionality is desired or
+  required, use e.g. ``py::bind_vector<VecType, py::smart_holder>``.
+
+* Gradually migrate from ``py::enum_`` to ``py::native_enum`` to improve
+  integration with Python's standard enum types.
+
+There is no urgency to refactor existing, working bindings — adopt new
+features as the need arises or as part of ongoing maintenance efforts.
+
+If you are using CMake, update to FindPython variables (mostly changing
+variables from ``PYTHON_*`` -> ``Python_*``). You should see if you can use
+``set(PYBIND11_FINDPYTHON ON)``, which has been supported for years and will
+avoid setting the compatibly mode variables.
+
+Potential stumbling blocks when migrating to v3.0
+-------------------------------------------------
+
+The following issues are very unlikely to arise, and easy to work around:
+
+* In rare cases, a C++ enum may be bound to Python via a
+  :ref:`custom type caster <custom_type_caster>`. In such cases, a
+  template specialization like this may be required:
+
+  .. code-block:: cpp
+
+      #if defined(PYBIND11_HAS_NATIVE_ENUM)
+      namespace pybind11::detail {
+      template <typename FancyEnum>
+      struct type_caster_enum_type_enabled<
+          FancyEnum,
+          enable_if_t<is_fancy_enum<FancyEnum>::value>> : std::false_type {};
+      }
+      #endif
+
+  This specialization is needed only if the custom type caster is templated.
+
+  The ``PYBIND11_HAS_NATIVE_ENUM`` guard is needed only
+  if backward compatibility with pybind11v2 is required.
+
+* Similarly, template specializations like the following may be required
+  if there are custom
+
+  * ``pybind11::detail::copyable_holder_caster`` or
+
+  * ``pybind11::detail::move_only_holder_caster``
+
+  implementations that are used for ``std::shared_ptr`` or ``std::unique_ptr``
+  conversions:
+
+  .. code-block:: cpp
+
+      #if defined(PYBIND11_HAS_INTERNALS_WITH_SMART_HOLDER_SUPPORT)
+      namespace pybind11::detail {
+      template <typename ExampleType>
+      struct copyable_holder_caster_shared_ptr_with_smart_holder_support_enabled<
+          ExampleType,
+          enable_if_t<is_example_type<ExampleType>::value>> : std::false_type {};
+      }
+      #endif
+
+  .. code-block:: cpp
+
+      #if defined(PYBIND11_HAS_INTERNALS_WITH_SMART_HOLDER_SUPPORT)
+      namespace pybind11::detail {
+      template <typename ExampleType>
+      struct move_only_holder_caster_unique_ptr_with_smart_holder_support_enabled<
+          ExampleType,
+          enable_if_t<is_example_type<ExampleType>::value>> : std::false_type {};
+      }
+      #endif
+
+  The ``PYBIND11_HAS_INTERNALS_WITH_SMART_HOLDER_SUPPORT`` guard is needed only
+  if backward compatibility with pybind11v2 is required.
+
+  (Note that ``copyable_holder_caster`` and ``move_only_holder_caster`` are not
+  documented, although they existed since 2017.)
+
+
 .. _upgrade-guide-2.12:
 
 v2.12

include/pybind11/detail/common.h

@@ -16,11 +16,11 @@
 
 #define PYBIND11_VERSION_MAJOR 3
 #define PYBIND11_VERSION_MINOR 0
-#define PYBIND11_VERSION_PATCH 0.dev1
+#define PYBIND11_VERSION_PATCH 0rc1
 
 // Similar to Python's convention: https://docs.python.org/3/c-api/apiabiversion.html
-// Additional convention: 0xD = dev
+// Use 0xA0 for dev
-#define PYBIND11_VERSION_HEX 0x030000D1
+#define PYBIND11_VERSION_HEX 0x030000C1
 
 #include "pybind11_namespace_macros.h"
 

tests/extra_python_package/test_files.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import contextlib
 import os
+import re
 import shutil
 import subprocess
 import sys
@@ -15,6 +16,7 @@ from typing import Generator
 DIR = Path(__file__).parent.resolve()
 MAIN_DIR = DIR.parent.parent
 
+FILENAME_VERSION = re.compile(r"[-_]((\d+\.\d+\.\d+)(?:[a-z]+\d*)?)(?:-|\.tar\.gz$)")
 
 # Newer pytest has global path setting, but keeping old pytest for now
 sys.path.append(str(MAIN_DIR / "tools"))
@@ -184,7 +186,7 @@ def test_build_sdist(monkeypatch, tmpdir):
     )
 
     (sdist,) = tmpdir.visit("*.tar.gz")
-    version = sdist.basename.split("-")[1][:-7]
+    version = FILENAME_VERSION.search(sdist.basename).group(1)
 
     with tarfile.open(str(sdist), "r:gz") as tar:
         simpler = {n.split("/", 1)[-1] for n in tar.getnames()[1:]}
@@ -197,6 +199,7 @@ def test_build_sdist(monkeypatch, tmpdir):
     assert files <= simpler
 
     assert b'name = "pybind11"' in pyproject_toml
+    assert f"Version: {version}" in pkg_info
     assert "License-Expression: BSD-3-Clause" in pkg_info
     assert "License-File: LICENSE" in pkg_info
     assert "Provides-Extra: global" in pkg_info
@@ -220,6 +223,7 @@ def test_build_global_dist(monkeypatch, tmpdir):
         )
 
     (sdist,) = tmpdir.visit("*.tar.gz")
+    version = FILENAME_VERSION.search(sdist.basename).group(2)
 
     with tarfile.open(str(sdist), "r:gz") as tar:
         simpler = {n.split("/", 1)[-1] for n in tar.getnames()[1:]}
@@ -232,6 +236,7 @@ def test_build_global_dist(monkeypatch, tmpdir):
     assert files <= simpler
 
     assert b'name = "pybind11-global"' in pyproject_toml
+    assert f"Version: {version}" in pkg_info
     assert "License-Expression: BSD-3-Clause" in pkg_info
     assert "License-File: LICENSE" in pkg_info
     assert "Provides-Extra: global" not in pkg_info
@@ -247,6 +252,7 @@ def tests_build_wheel(monkeypatch, tmpdir):
     )
 
     (wheel,) = tmpdir.visit("*.whl")
+    version, simple_version = FILENAME_VERSION.search(wheel.basename).groups()
 
     files = {f"pybind11/{n}" for n in all_files}
     files |= {
@@ -274,11 +280,10 @@ def tests_build_wheel(monkeypatch, tmpdir):
 
     assert 'set(pybind11_INCLUDE_DIR "${PACKAGE_PREFIX_DIR}/include")' in cmakeconfig
 
-    version = wheel.basename.split("-")[1]
-    simple_version = ".".join(version.split(".")[:3])
     pkgconfig_expected = PKGCONFIG.format(VERSION=simple_version)
     assert pkgconfig_expected == pkgconfig
 
+    assert f"Version: {version}" in pkg_info
     assert "License-Expression: BSD-3-Clause" in pkg_info
     assert "License-File: LICENSE" in pkg_info
     assert "Provides-Extra: global" in pkg_info
@@ -302,6 +307,7 @@ def tests_build_global_wheel(monkeypatch, tmpdir):
         )
 
     (wheel,) = tmpdir.visit("*.whl")
+    version, simple_version = FILENAME_VERSION.search(wheel.basename).groups()
 
     files = {f"data/data/{n}" for n in headers}
     files |= {f"data/headers/{n[8:]}" for n in headers}
@@ -326,6 +332,7 @@ def tests_build_global_wheel(monkeypatch, tmpdir):
         (pkg_info_path,) = (n for n in names if n.endswith("METADATA"))
         pkg_info = zipfile.Path(z, pkg_info_path).read_text(encoding="utf-8")
 
+    assert f"Version: {version}" in pkg_info
     assert "License-Expression: BSD-3-Clause" in pkg_info
     assert "License-File: LICENSE" in pkg_info
     assert "Provides-Extra: global" not in pkg_info
@@ -337,7 +344,5 @@ def tests_build_global_wheel(monkeypatch, tmpdir):
 
     assert 'set(pybind11_INCLUDE_DIR "${PACKAGE_PREFIX_DIR}/include")' in cmakeconfig
 
-    version = wheel.basename.split("-")[1]
-    simple_version = ".".join(version.split(".")[:3])
     pkgconfig_expected = PKGCONFIG.format(VERSION=simple_version)
     assert pkgconfig_expected == pkgconfig

tests/test_custom_type_setup.cpp

@@ -26,7 +26,7 @@ TEST_SUBMODULE(custom_type_setup, m) {
             auto *type = &heap_type->ht_type;
             type->tp_flags |= Py_TPFLAGS_HAVE_GC;
             type->tp_traverse = [](PyObject *self_base, visitproc visit, void *arg) {
-        // https://docs.python.org/3/c-api/typeobj.html#c.PyTypeObject.tp_traverse
+// https://docs.python.org/3/c-api/typeobj.html#c.PyTypeObject.tp_traverse
 #if PY_VERSION_HEX >= 0x03090000
                 Py_VISIT(Py_TYPE(self_base));
 #endif

tools/make_changelog.py

@@ -42,10 +42,12 @@ cats_descr = {
     "fix": "Bug fixes",
     "fix(types)": "",
     "fix(cmake)": "",
+    "fix(free-threading)": "",
     "docs": "Documentation",
     "tests": "Tests",
     "ci": "CI",
     "chore": "Other",
+    "chore(cmake)": "",
     "unknown": "Uncategorised",
 }
 cats: dict[str, list[str]] = {c: [] for c in cats_descr}

tools/pybind11Config.cmake.in

@@ -68,11 +68,11 @@ maximum version of CMake to 3.27+, then FindPython is the default (since
 FindPythonInterp/FindPythonLibs has been removed via policy `CMP0148`).
 
 Starting in pybind11 3.0, the new mode is the default, but we provide backward
-compatible names (`PYTHON_*` vs. the new `Python_* names). Set the mode
+compatible names (``PYTHON_*`` vs. the new ``Python_*`` names). Set the mode
 explicitly to avoid the compatibility defines. You can specify this mode
-explicitly by setting `PYBIND11_FINDPYTHON` to `COMPAT`, but if you are changing
+explicitly by setting ``PYBIND11_FINDPYTHON`` to ``COMPAT``, but if you are changing
-your CMakeLists anyway, please just use the `ON` mode. A future release may
+your CMakeLists anyway, please just use the ``ON`` mode. A future release may
-default to `ON`.
+default to ``ON``.
 
 New FindPython mode
 ^^^^^^^^^^^^^^^^^^^