gh-89373: Document that error indicator may be set in tp_dealloc

Doc/c-api/typeobj.rst

@@ -686,6 +686,24 @@ and :c:data:`PyType_Type` effectively act as defaults.)
    instance, and call the type's :c:member:`~PyTypeObject.tp_free` function to
    free the object itself.
 
+   If you may call functions that may set the error indicator, you must
+   use :c:func:`PyErr_Fetch` and :c:func:`PyErr_Restore` to ensure you
+   don't clobber a preexisting error indicator (the deallocation could
+   have occurred while processing a different error):
+
+   .. code-block:: c
+
+     static void foo_dealloc(foo_object *self) {
+         PyObject *et, *ev, *etb;
+         PyErr_Fetch(&et, &ev, &etb);
+         ...
+         PyErr_Restore(et, ev, etb);
+     }
+
+   The dealloc handler itself must not raise an exception; if it hits an error
+   case it should call :c:func:`PyErr_WriteUnraisable` to log (and clear) an
+   unraisable exception.
+
    No guarantees are made about when an object is destroyed, except:
 
    * Python will destroy an object immediately or some time after the final

Misc/NEWS.d/next/Documentation/2021-09-15-13-07-25.bpo-45210.RtGk7i.rst

@@ -0,0 +1,2 @@
+Document that error indicator may be set in tp_dealloc, and how to avoid
+clobbering it.