docs: prepare for v3.0.0rc1

[rwgk]

Description

PENDING:

• Make another pass updating the Changelog, reviewing the Upgrade guide.
• Move changelog to markdown (after this changelog update is merged)
• Ecosystem compatibility page similar to numpy 2.0

Suggested changelog entry:

[henryiii]

We should highlight the CMake change, moving the default to FindPython will affect a lot, even with the back-compat tricks we used. For example, this will no longer work cmake -DPYTHON_EXECUTABLE=..., it needs to be cmake -DPython_EXECUTABLE=....

We can do the changelog in a separate PR if you prefer, that's mostly autogenerated so might be easier to split them up.

[rwgk]

We can do the changelog in a separate PR if you prefer, that's mostly autogenerated so might be easier to split them up.

I was actually hoping that we can collaborate here, working on the Upgrade guide and Changlog together.

I'm mostly done with the Upgrade guide, except for two small-ish TODOs, to explain a couple traits structures. (I still need to add a couple matching tests.)

It'd be awesome if you could make a first pass for the Changelog. Maybe some items from there should be added to the Upgrade guide, and maybe we don't have to mention #5580 in the Upgrade guide, only the Changelog?

[henryiii]

I'll try to do that soon.

[henryiii]

Reminder TODO (maybe mostly to self): I'd like to try the scikit-build-core conversion and convert the changelog to markdown before 3.0.

[henryiii]

Which ones of these might we want to clean up for 3.0?

Feature	Deprecated Version	Year	Notes
py::metaclass()	2.1	2017	A tiny bit of usage
PYBIND11_PLUGIN	2.2	2017	Still used (~3% on GitHub, but inflated by pybind11 forks), possibly in legacy code.
make_simple_namespace	2.8.1	2021	Added in 2.8.0, I can't find any usage
py::set_error() replacing operator()	2.12	2024
get_type_overload	2.6	2020
call()	2.0	2016
.str()	?
.get_type()	2.6 (no message)		Making this produce a warning in #5596
== and !=	2.2	2017	Error prone
.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	?

(Used ChatGPT to make that a table instead of a list)

These are clearly unused:

• feat: drop PYBIND11_NUMPY_1_ONLY #5595 (has discussion about how much to drop)
• feat: remove make_simple_namespace #5597

[rwgk]

@henryiii I'm done with a round of adding some new material ...

• 350b435

• 6281115

... and a few tiny fix-up commits:

• c528b75

• c87a445

• 4524619

• 0088e25

There is also #5603, adding a unit test to ensure that people can find a certain-to-work example after looking at the Upgrade guide. It'd be great to get that merged.

Next I'll try to work through the PENDING CLEANUP listed in the PR description.

[dyollb]

I am starting to try out the current master branch (mainly to get access to py::native_enum). Do you have any idea when you will release v3? I will report any issues I face porting from v2.13.6 and also test if pybind11-stubgen needs to be updated ...

• a first thing I noticed is that the new native_enum does not seem to allow class doc strings, only value docstrings (see [BUG]: the new native_enum does not support class doc strings #5615).
• also: pybind11-stubgen is not yet able to properly handle py::native_enum: New pybind11::native_enum not supported sizmailov/pybind11-stubgen#249

[rwgk]

Do you have any idea when you will release v3?

Just speaking for myself: I was thinking a week or so after we merge #5564.

[henryiii]

I'd also like to get #5598 in, I have a little to finish there. After that, I think we could make a beta or rc release, then maybe a week or so for full release?

[henryiii]

Will drop this table in the docs somewhere, and add a warning in the changelog/upgrade guide that 3.x releases may remove anything producing a deprecation warning in 3.0. Any deprecation warnings introduced after 3.0 will be kept till at least 4.0.

Feature	Deprecated Version	Year	Notes
py::metaclass()	2.1	2017	A tiny bit of usage
PYBIND11_PLUGIN	2.2	2017	Still used (~3% on GitHub, but inflated by pybind11 forks), possibly in legacy code.
py::set_error() replacing operator()	2.12	2024
get_type_overload	2.6	2020
call()	2.0	2016
.str()	?
.get_type()	2.6		Didn't warn until 3.0
== and !=	2.2	2017	Error prone
.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	?

[Copilot]

Pull Request Overview

This PR prepares for the v3.0.0 release by adding an upgrade guide, expanding the changelog, and refining related tooling and documentation.

• Introduce a detailed docs/upgrade.rst guide for migrating to v3.0
• Overhaul docs/changelog.rst with categorized entries and update make_changelog.py to recognize new prefixes
• Add a deprecation table in docs/advanced/deprecated.rst and tidy minor formatting in CMake and class docs

Reviewed Changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tools/pybind11Config.cmake.in	Switch inline code to double-backtick formatting
tools/make_changelog.py	Add new changelog categories for free-threading and CMake
docs/upgrade.rst	Add v3.0 upgrade guide
docs/classes.rst	Remove std:: qualifier for enable_if_t in example
docs/changelog.rst	Populate in-development changelog for v3.0.0
docs/advanced/deprecated.rst	Add table of deprecated features

Comments suppressed due to low confidence (2)

docs/upgrade.rst:28

• There's a duplicate word "some" in "we do some some backward compatibility"; consider reducing to "we provide backward compatibility" or similar.

If you haven't moved, we do some some backward compatibility ``PYTHON_*`` variables, but

docs/classes.rst:645

• Ensure that enable_if_t is in scope (e.g. via using std::enable_if_t or fully qualifying it) so that the example remains valid.

enable_if_t<is_fancy_enum<FancyEnum>::value>> : std::false_type {};

[henryiii]

The low confidence comments were useful and the actual comments were not. :)

I've changed the versioning convention to match CPython, where D1 is the development branch. We were using D1, which comes after the alpha/beta/rc's. Which means that if someone were checking this, this RC is actually a lower version than the development branch. CPython sets A0 as soon as work starts on that version, and A1 for the first dev release.

Let's merge this soon, so I can do a followup that reworks the changelog into markdown. We also have a ton of breathe warnings, it would be nice to at least fix the one about the unexpected indentation. It might be hard to find, though, since it doesn't give a location.

[rwgk]

I made a few minor corrections. Please see the last 5 tiny commits.

Let's merge this soon

Sounds good! Please go ahead.