docs: known issues (#2565)

* docs: FAQ CMake updates

* docs: limitations

* ci: don't over label

* docs: update CHANGELOG, add a bit more structure

* ci: label PRs with more labels, and sooner

* docs: updates from @rwgk

* docs: address @YannickJadoul's points

.github/labeler.yml

+needs changelog:
+  - all:
+    - '!docs/changelog.rst'
+    any:
+    - 'include/pybind11/**/*'
+    - 'pybind11/**/*'
+    - 'tools/**/*'
+    - 'CMakeLists.txt'
+
+docs:
+  - any:
+    - 'docs/basics.rst'
+    - 'docs/benchmark.rst'
+    - 'docs/classes.rst'
+    - 'docs/compiling.rst'
+    - 'docs/faq.rst'
+    - 'docs/index.rst'
+    - 'docs/installing.rst'
+    - 'docs/limitations.rst'
+    - 'docs/reference.rst'
+    - 'docs/release.rst'
+    - 'docs/advanced/**/*.rst'
+    - 'docs/cmake/**/*.rst'
+
+
+ci:
+  - any:
+    - '.github/workflows/*.yaml'

.github/labeler_merged.yml

-needs changelog:
-  - all: ['!docs/changelog.rst']

.github/workflows/pr_merged.yml → .github/workflows/labeler.yml

 name: PR merged
 name: PR merged
 on:
 on:
   pull_request_target:
   pull_request_target:
-    types: [closed]
+    types: [opened, reopened, synchronize, edited, closed]
 
 
 jobs:
 jobs:
   label-merged:
   label-merged:
     name: Changelog needed
     name: Changelog needed
     runs-on: ubuntu-latest
     runs-on: ubuntu-latest
-    if: github.event.pull_request.merged == true
+    if: "!(github.event.action == 'closed' && github.event.pull_request.merged == false)"
     steps:
     steps:
     - uses: actions/labeler@main
     - uses: actions/labeler@main
       with:
       with:
         repo-token: ${{ secrets.GITHUB_TOKEN }}
         repo-token: ${{ secrets.GITHUB_TOKEN }}
-        configuration-path: .github/labeler_merged.yml
+        sync-labels: true

docs/faq.rst

@@ -27,18 +27,6 @@ The Python interpreter immediately crashes when importing my module
 
 
 See the first answer.
 See the first answer.
 
 
-CMake doesn't detect the right Python version
-=============================================
-
-The CMake-based build system will try to automatically detect the installed
-version of Python and link against that. When this fails, or when there are
-multiple versions of Python and it finds the wrong one, delete
-``CMakeCache.txt`` and then invoke CMake as follows:
-
-.. code-block:: bash
-
-    cmake -DPYTHON_EXECUTABLE:FILEPATH=<path-to-python-executable> .
-
 .. _faq_reference_arguments:
 .. _faq_reference_arguments:
 
 
 Limitations involving reference arguments
 Limitations involving reference arguments
@@ -275,17 +263,34 @@ been received, you must either explicitly interrupt execution by throwing
         });
         });
     }
     }
 
 
+CMake doesn't detect the right Python version
+=============================================
+
+The CMake-based build system will try to automatically detect the installed
+version of Python and link against that. When this fails, or when there are
+multiple versions of Python and it finds the wrong one, delete
+``CMakeCache.txt`` and then add ``-DPYTHON_EXECUTABLE=$(which python)`` to your
+CMake configure line. (Replace ``$(which python)`` with a path to python if
+your prefer.)
+
+You can alternatively try ``-DPYBIND11_FINDPYTHON=ON``, which will activate the
+new CMake FindPython support instead of pybind11's custom search. Requires
+CMake 3.12+, and 3.15+ or 3.18.2+ are even better. You can set this in your
+``CMakeLists.txt`` before adding or finding pybind11, as well.
+
 Inconsistent detection of Python version in CMake and pybind11
 Inconsistent detection of Python version in CMake and pybind11
 ==============================================================
 ==============================================================
 
 
-The functions ``find_package(PythonInterp)`` and ``find_package(PythonLibs)`` provided by CMake
-for Python version detection are not used by pybind11 due to unreliability and limitations that make
-them unsuitable for pybind11's needs. Instead pybind provides its own, more reliable Python detection
-CMake code. Conflicts can arise, however, when using pybind11 in a project that *also* uses the CMake
-Python detection in a system with several Python versions installed.
+The functions ``find_package(PythonInterp)`` and ``find_package(PythonLibs)``
+provided by CMake for Python version detection are modified by pybind11 due to
+unreliability and limitations that make them unsuitable for pybind11's needs.
+Instead pybind11 provides its own, more reliable Python detection CMake code.
+Conflicts can arise, however, when using pybind11 in a project that *also* uses
+the CMake Python detection in a system with several Python versions installed.
 
 
-This difference may cause inconsistencies and errors if *both* mechanisms are used in the same project. Consider the following
-CMake code executed in a system with Python 2.7 and 3.x installed:
+This difference may cause inconsistencies and errors if *both* mechanisms are
+used in the same project. Consider the following CMake code executed in a
+system with Python 2.7 and 3.x installed:
 
 
 .. code-block:: cmake
 .. code-block:: cmake
 
 
@@ -303,10 +308,24 @@ In contrast this code:
     find_package(PythonInterp)
     find_package(PythonInterp)
     find_package(PythonLibs)
     find_package(PythonLibs)
 
 
-will detect Python 3.x for pybind11 and may crash on ``find_package(PythonLibs)`` afterwards.
-
-It is advised to avoid using ``find_package(PythonInterp)`` and ``find_package(PythonLibs)`` from CMake and rely
-on pybind11 in detecting Python version. If this is not possible CMake machinery should be called *before* including pybind11.
+will detect Python 3.x for pybind11 and may crash on
+``find_package(PythonLibs)`` afterwards.
+
+There are three possible solutions:
+
+1. Avoid using ``find_package(PythonInterp)`` and ``find_package(PythonLibs)``
+   from CMake and rely on pybind11 in detecting Python version. If this is not
+   possible, the CMake machinery should be called *before* including pybind11.
+2. Set ``PYBIND11_FINDPYTHON`` to ``True`` or use ``find_package(Python
+   COMPONENTS Interpreter Development)`` on modern CMake (3.12+, 3.15+ better,
+   3.18.2+ best). Pybind11 in these cases uses the new CMake FindPython instead
+   of the old, deprecated search tools, and these modules are much better at
+   finding the correct Python.
+3. Set ``PYBIND11_NOPYTHON`` to ``TRUE``. Pybind11 will not search for Python.
+   However, you will have to use the target-based system, and do more setup
+   yourself, because it does not know about or include things that depend on
+   Python, like ``pybind11_add_module``. This might be ideal for integrating
+   into an existing system, like scikit-build's Python helpers.
 
 
 How to cite this project?
 How to cite this project?
 =========================
 =========================

docs/limitations.rst

 Limitations
 Limitations
 ###########
 ###########
 
 
+Design choices
+^^^^^^^^^^^^^^
+
 pybind11 strives to be a general solution to binding generation, but it also has
 pybind11 strives to be a general solution to binding generation, but it also has
 certain limitations:
 certain limitations:
 
 
@@ -11,9 +14,43 @@ certain limitations:
 
 
 - The NumPy interface ``pybind11::array`` greatly simplifies accessing
 - The NumPy interface ``pybind11::array`` greatly simplifies accessing
   numerical data from C++ (and vice versa), but it's not a full-blown array
   numerical data from C++ (and vice versa), but it's not a full-blown array
-  class like ``Eigen::Array`` or ``boost.multi_array``.
+  class like ``Eigen::Array`` or ``boost.multi_array``. ``Eigen`` objects are
+  directly supported, however, with ``pybind11/eigen.h``.
+
+Large but useful features could be implemented in pybind11 but would lead to a
+significant increase in complexity. Pybind11 strives to be simple and compact.
+Users who require large new features are encouraged to write an extension to
+pybind11; see `pybind11_json <https://github.com/pybind/pybind11_json>`_ for an
+example.
+
+
+Known bugs
+^^^^^^^^^^
+
+These are issues that hopefully will one day be fixed, but currently are
+unsolved. If you know how to help with one of these issues, contributions
+are welcome!
+
+- The test suite currently segfaults on macOS and Python 3.9.0 when exiting the
+  interpreter.  This was suspected to be related to the cross module GIL code,
+  but could be a broader Python 3.9.0 issue.
+  `#2558 <https://github.com/pybind/pybind11/issues/2558>`_
+
+- The ``cpptest`` does not run on Windows with Python 3.8 or newer, due to DLL
+  loader changes. User code that is correctly installed should not be affected.
+  `#2560 <https://github.com/pybind/pybind11/pull/2560>`_
+
+- There may be a rare issue with leakage under some compilers, exposed by
+  adding an unrelated test to the test suite.
+  `#2335 <https://github.com/pybind/pybind11/pull/2335>`_
+
+Known limitations
+^^^^^^^^^^^^^^^^^
+
+These are issues that are probably solvable, but have not been fixed yet. A
+clean, well written patch would likely be accepted to solve them.
 
 
-These features could be implemented but would lead to a significant increase in
-complexity. I've decided to draw the line here to keep this project simple and
-compact. Users who absolutely require these features are encouraged to fork
-pybind11.
+- Type casters are not kept alive recursively.
+  `#2527 <https://github.com/pybind/pybind11/issues/2527>`_
+  One consequence is that containers of ``char *`` are currently not supported.
+  `#2245 <https://github.com/pybind/pybind11/issues/2245>`_

docs/upgrade.rst

@@ -13,10 +13,19 @@ modernization and other useful information.
 v2.6
 v2.6
 ====
 ====
 
 
-The ``tools/clang`` submodule and ``tools/mkdoc.py`` have been moved to a
-standalone package, `pybind11-mkdoc`_. If you were using those tools, please
-use them via a pip install from the new location.
+Usage of the ``PYBIND11_OVERLOAD*`` macros and ``get_overload`` function should
+be replaced by ``PYBIND11_OVERRIDE*`` and ``get_override``. In the future, the
+old macros may be deprecated and removed.
+
+``py::module`` has been renamed ``py::module_``, but a backward compatible
+typedef has been included. This change was to avoid a language change in C++20
+that requires unqualified ``module`` not be placed at the start of a logical
+line. Qualified usage is unaffected and the typedef will remain unless the
+C++ language rules change again.
 
 
+The public constructors of ``py::module_`` have been deprecated. Use
+``PYBIND11_MODULE`` or ``module_::create_extension_module`` instead.
+**Provisional in 2.6.0rc1.**
 
 
 An error is now thrown when ``__init__`` is forgotten on subclasses. This was
 An error is now thrown when ``__init__`` is forgotten on subclasses. This was
 incorrect before, but was not checked. Add a call to ``__init__`` if it is
 incorrect before, but was not checked. Add a call to ``__init__`` if it is
@@ -37,9 +46,13 @@ If ``__eq__`` defined but not ``__hash__``, ``__hash__`` is now set to
 ``None``, as in normal CPython. You should add ``__hash__`` if you intended the
 ``None``, as in normal CPython. You should add ``__hash__`` if you intended the
 class to be hashable, possibly using the new ``py::hash`` shortcut.
 class to be hashable, possibly using the new ``py::hash`` shortcut.
 
 
-Usage of the ``PYBIND11_OVERLOAD*`` macros and ``get_overload`` function should
-be replaced by ``PYBIND11_OVERRIDE*`` and ``get_override``. In the future, the
-old macros may be deprecated and removed.
+The constructors for ``py::array`` now always take signed integers for size,
+for consistency. This may lead to compiler warnings on some systems. Cast to
+``py::ssize_t`` instead of ``std::size_t``.
+
+The ``tools/clang`` submodule and ``tools/mkdoc.py`` have been moved to a
+standalone package, `pybind11-mkdoc`_. If you were using those tools, please
+use them via a pip install from the new location.
 
 
 The ``pybind11`` package on PyPI no longer fills the wheel "headers" slot - if
 The ``pybind11`` package on PyPI no longer fills the wheel "headers" slot - if
 you were using the headers from this slot, they are available by requesting the
 you were using the headers from this slot, they are available by requesting the