docs: update upgrade guide

Author: henryiii

docs/upgrade.rst

@@ -8,6 +8,22 @@ to a new version. But it goes into more detail. This includes things like
 deprecated APIs and their replacements, build system changes, general code
 modernization and other useful information.
 
+.. _upgrade-guide-2.10:
+
+v2.10
+=====
+
+The current scoped GIL implementation doesn't support nested access. In pybind11
+In 2.10.1, a configuration option ``PYBIND11_SIMPLE_GIL`` was added, defaulting
+to OFF; the simpler GIL implemntation supports nested access, but does not
+support dissociation (the ``true`` parameter of ``gil_scope_release``).  In
+pybind11 2.11, we plan to change the default to ON. If you need the old
+behavior, please set ``PYBIND11_SIMPLE_GIL`` to OFF. We plan to have an example
+for manually supporting dissociation.
+
+There may be an unconfirmed ABI breakage between 2.9 and 2.10. We plan to bump
+the internals number in 2.11.
+
 .. _upgrade-guide-2.9:
 
 v2.9