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

docs/limitations.rst

@@ -1,6 +1,9 @@
 Limitations
 ###########
 
+Design choices
+^^^^^^^^^^^^^^
+
 pybind11 strives to be a general solution to binding generation, but it also has
 certain limitations:
 
@@ -11,9 +14,43 @@ certain limitations:
 
 - The NumPy interface ``pybind11::array`` greatly simplifies accessing
   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``.
 
-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.
+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.
+
+- 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>`_