[WIP] Preparation for v3.0.0 release: Upgrade guide & Changelog

[rwgk]

Description

PENDING:

• Review/merge PR Support for sub-interpreters #5564
• Finalize/merge PR chore: use scikit-build-core for the build #5598
• Make another pass updating the Changelog, reviewing the Upgrade guide.
• Ecosystem compatibility page similar to numpy 2.0

Suggested changelog entry:

---

Browse prepv300/manuscript tree

Browse prepv300/manuscript commits

[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?