Document C API changes in What's New in Python 3.8 (GH-14092)

(cherry picked from commit bd5798f6d4f6960fd6b49976bdf4326be77f4277)

Co-authored-by: Victor Stinner <vstinner@redhat.com>

1 files changed, 27 insertions, 0 deletions

diff --git a/Doc/whatsnew/3.8.rst b/Doc/whatsnew/3.8.rst
index 9989a09..05d2ecc 100644
--- a/Doc/whatsnew/3.8.rst
+++ b/Doc/whatsnew/3.8.rst
@@ -936,6 +936,33 @@ Optimizations
 Build and C API Changes
 =======================
 
+* The header files have been reorganized to better separate the different kinds
+  of APIs:
+
+  * ``Include/*.h`` should be the portable public stable C API.
+  * ``Include/cpython/*.h`` should be the unstable C API specific to CPython;
+     public API, with some private API prefixed by ``_Py`` or ``_PY``.
+  * ``Include/internal/*.h`` is the private internal C API very specific to
+    CPython. This API comes with no backward compatibility warranty and should
+    not be used outside CPython. It is only exposed for very specific needs
+    like debuggers and profiles which has to access to CPython internals
+    without calling functions. This API is now installed by ``make install``.
+
+  (Contributed by Victor Stinner in :issue:`35134` and :issue:`35081`,
+  work initiated by Eric Snow in Python 3.7)
+
+* Some macros have been converted to static inline functions: parameter types
+  and return type are well defined, they don't have issues specific to macros,
+  variables have a local scopes. Examples:
+
+  * :c:func:`Py_INCREF`, :c:func:`Py_DECREF`
+  * :c:func:`Py_XINCREF`, :c:func:`Py_XDECREF`
+  * :c:func:`PyObject_INIT`, :c:func:`PyObject_INIT_VAR`
+  * Private functions: :c:func:`_PyObject_GC_TRACK`,
+    :c:func:`_PyObject_GC_UNTRACK`, :c:func:`_Py_Dealloc`
+
+  (Contributed by Victor Stinner in :issue:`35059`.)
+
 * The :c:func:`PyByteArray_Init` and :c:func:`PyByteArray_Fini` functions have
   been removed. They did nothing since Python 2.7.4 and Python 3.2.0, were
   excluded from the limited API (stable ABI), and were not documented.