Cleanup What's New in Python 3.14 (C API changes) (python#129341)

* Document PyDictObject.ma_version_tag removal.
* Add "Limited C API Changes" section.
* Move entries from New Features to Porting to Python 3.14.
* Include Pending removal documents at the right place.

Author: vstinner

Doc/deprecations/c-api-pending-removal-in-future.rst

@@ -34,7 +34,6 @@ although there is currently no date scheduled for their removal.
   Use :c:func:`!_PyErr_ChainExceptions1` instead.
 * :c:member:`!PyBytesObject.ob_shash` member:
   call :c:func:`PyObject_Hash` instead.
-* :c:member:`!PyDictObject.ma_version_tag` member.
 * Thread Local Storage (TLS) API:
 
   * :c:func:`PyThread_create_key`:

Doc/whatsnew/3.14.rst

@@ -1218,16 +1218,6 @@ New features
   which has an ambiguous return value.
   (Contributed by Irit Katriel and Erlend Aasland in :gh:`105201`.)
 
-* :c:func:`Py_Finalize` now deletes all interned strings. This
-  is backwards incompatible to any C-Extension that holds onto an interned
-  string after a call to :c:func:`Py_Finalize` and is then reused after a
-  call to :c:func:`Py_Initialize`.  Any issues arising from this behavior will
-  normally result in crashes during the execution of the subsequent call to
-  :c:func:`Py_Initialize` from accessing uninitialized memory. To fix, use
-  an address sanitizer to identify any use-after-free coming from
-  an interned string and deallocate it during module shutdown.
-  (Contributed by Eddie Elizondo in :gh:`113601`.)
-
 * Add :c:func:`PyLong_IsPositive`, :c:func:`PyLong_IsNegative`
   and :c:func:`PyLong_IsZero` for checking if :c:type:`PyLongObject`
   is positive, negative, or zero, respectively.
@@ -1303,18 +1293,12 @@ New features
   test if two strings are equal.
   (Contributed by Victor Stinner in :gh:`124502`.)
 
-
 * Add :c:func:`PyType_Freeze` function to make a type immutable.
   (Contributed by Victor Stinner in :gh:`121654`.)
 
 * Add :c:func:`PyUnstable_Object_EnableDeferredRefcount` for enabling
   deferred reference counting, as outlined in :pep:`703`.
 
-* The :ref:`Unicode Exception Objects <unicodeexceptions>` C API
-  now raises a :exc:`TypeError` if its exception argument is not
-  a :exc:`UnicodeError` object.
-  (Contributed by Bénédikt Tran in :gh:`127691`.)
-
 * Add :c:func:`PyMonitoring_FireBranchLeftEvent` and
   :c:func:`PyMonitoring_FireBranchRightEvent` for generating
   :monitoring-event:`BRANCH_LEFT` and :monitoring-event:`BRANCH_RIGHT`
@@ -1334,14 +1318,33 @@ New features
   for debugging purposes.
 
 
-Porting to Python 3.14
-----------------------
+Limited C API changes
+---------------------
 
 * In the limited C API 3.14 and newer, :c:func:`Py_TYPE` and
   :c:func:`Py_REFCNT` are now implemented as an opaque function call to hide
   implementation details.
   (Contributed by Victor Stinner in :gh:`120600` and :gh:`124127`.)
 
+
+Porting to Python 3.14
+----------------------
+
+* :c:func:`Py_Finalize` now deletes all interned strings. This
+  is backwards incompatible to any C-Extension that holds onto an interned
+  string after a call to :c:func:`Py_Finalize` and is then reused after a
+  call to :c:func:`Py_Initialize`.  Any issues arising from this behavior will
+  normally result in crashes during the execution of the subsequent call to
+  :c:func:`Py_Initialize` from accessing uninitialized memory. To fix, use
+  an address sanitizer to identify any use-after-free coming from
+  an interned string and deallocate it during module shutdown.
+  (Contributed by Eddie Elizondo in :gh:`113601`.)
+
+* The :ref:`Unicode Exception Objects <unicodeexceptions>` C API
+  now raises a :exc:`TypeError` if its exception argument is not
+  a :exc:`UnicodeError` object.
+  (Contributed by Bénédikt Tran in :gh:`127691`.)
+
 * Private functions promoted to public C APIs:
 
   * ``_PyBytes_Join()``: :c:func:`PyBytes_Join`;
@@ -1386,12 +1389,6 @@ Deprecated
 
 .. Add C API deprecations above alphabetically, not here at the end.
 
-.. include:: ../deprecations/c-api-pending-removal-in-3.15.rst
-
-.. include:: ../deprecations/c-api-pending-removal-in-3.18.rst
-
-.. include:: ../deprecations/c-api-pending-removal-in-future.rst
-
 * The ``PyMonitoring_FireBranchEvent`` function is deprecated and should
   be replaced with calls to :c:func:`PyMonitoring_FireBranchLeftEvent`
   and :c:func:`PyMonitoring_FireBranchRightEvent`.
@@ -1416,12 +1413,23 @@ Deprecated
   (Contributed by Victor Stinner in :gh:`128863`.)
 
 
+.. include:: ../deprecations/c-api-pending-removal-in-3.15.rst
+
+.. include:: ../deprecations/c-api-pending-removal-in-3.18.rst
+
+.. include:: ../deprecations/c-api-pending-removal-in-future.rst
+
+
 Removed
 -------
 
 * Creating :c:data:`immutable types <Py_TPFLAGS_IMMUTABLETYPE>` with mutable
   bases was deprecated since 3.12 and now raises a :exc:`TypeError`.
 
+* Remove ``PyDictObject.ma_version_tag`` member which was deprecated since
+  Python 3.12. Use the :c:func:`PyDict_AddWatcher` API instead.
+  (Contributed by Sam Gross in :gh:`124296`.)
+
 * Remove the private ``_Py_InitializeMain()`` function. It was a
   :term:`provisional API` added to Python 3.8 by :pep:`587`.
   (Contributed by Victor Stinner in :gh:`129033`.)