feat: new FindPython support (#2370)
* feat: FindPython support
* refactor: rename to PYBIND11_FINDPYTHON
* docs: Caps fixes
* feat: NOPYTHON mode
* test: check simple call
* docs: add changelog/upgrade guide
* feat: Support Python3 and Python2
* refactor: Use targets in tests
* fix: support CMake 3.4+
* feat: classic search also finds virtual environments
* docs: some updates from @wjakob's review
* fix: wrong name for QUIET mode variable, reported by @skoslowski
* refactor: cleaner output messaging
* fix: support debug Python's in FindPython mode too
* fixup! refactor: cleaner output messaging
* fix: missing pybind11_FOUND and pybind11_INCLUDE_DIR restored to subdir mode
* fix: nicer reporting of Python / PyPy
* fix: out-of-order variable fix
* docs: minor last-minute cleanup
diff --git a/docs/upgrade.rst b/docs/upgrade.rst
index 3f56973..98285eb 100644
--- a/docs/upgrade.rst
+++ b/docs/upgrade.rst
@@ -8,6 +8,53 @@
deprecated APIs and their replacements, build system changes, general code
modernization and other useful information.
+.. _upgrade-guide-2.6:
+
+v2.6
+====
+
+CMake support:
+--------------
+
+The minimum required version of CMake is now 3.4. Several details of the CMake
+support have been deprecated; warnings will be shown if you need to change
+something. The changes are:
+
+* ``PYBIND11_CPP_STANDARD=<platform-flag>`` is deprecated, please use
+ ``CMAKE_CXX_STANDARD=<number>`` instead, or any other valid CMake CXX or CUDA
+ standard selection method, like ``target_compile_features``.
+
+* If you do not request a standard, PyBind11 targets will compile with the
+ compiler default, but not less than C++11, instead of forcing C++14 always.
+ If you depend on the old behavior, please use ``set(CMAKE_CXX_STANDARD 14)``
+ instead.
+
+* Direct ``pybind11::module`` usage should always be accompanied by at least
+ ``set(CMAKE_CXX_VISIBILITY_PRESET hidden)`` or similar - it used to try to
+ manually force this compiler flag (but not correctly on all compilers or with
+ CUDA).
+
+* ``pybind11_add_module``'s ``SYSTEM`` argument is deprecated and does nothing;
+ linking now behaves like other imported libraries consistently in both
+ config and submodule mode, and behaves like a ``SYSTEM`` library by
+ default.
+
+* If ``PYTHON_EXECUTABLE`` is not set, virtual environments (``venv``,
+ ``virtualenv``, and ``conda``) are prioritized over the standard search
+ (similar to the new FindPython mode).
+
+In addition, the following changes may be of interest:
+
+* ``CMAKE_INTERPROCEDURAL_OPTIMIZATION`` will be respected by
+ ``pybind11_add_module`` if set instead of linking to ``pybind11::lto`` or
+ ``pybind11::thin_lto``.
+
+* Using ``find_package(Python COMPONENTS Interpreter Development)`` before
+ pybind11 will cause pybind11 to use the new Python mechanisms instead of its
+ own custom search, based on a patched version of classic
+ FindPythonInterp/FindPythonLibs. In the future, this may become the default.
+
+
v2.2
====