PEP 620: minor updates

pep-0620.rst

@@ -10,12 +10,12 @@ Python-Version: 3.10
 Abstract
 ========
 
-Introduce C API incompatible changes.
+Introduce C API incompatible changes to hide implementation details.
 
-Evolving CPython internals and adding new features is made simpler by
-reducing backward compatibility issues.
+Hiding implementation details reduces backward compatibility issues and
+so ease evolution of CPython internals and addition of new features.
 
-It becomes possible to experiment in CPython more advanced optimizations
+It makes possible to experiment in CPython more advanced optimizations
 than just micro-optimizations.
 
 Define a process to reduce the number of broken C extensions.
@@ -36,9 +36,8 @@ Adding or removing members of C structures is causing multiple
 implementation issues.
 
 Adding a new member breaks the stable ABI (PEP 384), especially for
-types declared statically with::
-
-    static PyTypeObject MyType = {...};
+types declared statically (e.g. ``static PyTypeObject MyType =
+{...};``).
 
 In Python 3.4, the PEP 442 "Safe object finalization" added
 ``tp_finalize`` member at the end of the ``PyTypeObject`` structure. For
@@ -122,7 +121,7 @@ be implemented on top on PyPy tracing garbage collector.
 
 These conversions are required because the Python C API is too close to
 the CPython implementation: there is no high-level abstraction.
-example, structures members are part of the public C API and nothing
+For example, structures members are part of the public C API and nothing
 prevents a C extension to get or set directly
 ``PyTupleObject.ob_item[0]`` (the first item of a tuple).
 
@@ -453,13 +452,13 @@ converted to static inline functions to disallow that.
 New pythoncapi_compat.h header file
 -----------------------------------
 
-Making structures opaque require to add getter and setter functions. C
-extensions must be modified to use these new functions. The practical
-issue is how to handle backward compatibility.
+Making structures opaque require to require to modify C extensions to
+use getter and setter functions. The practical issue is how to keep
+support for old Python versions which don't have these functions.
 
-In Python 3.10, it is no longer possible to use ``Py_TYPE()`` as an
-l-value. The new ``Py_SET_TYPE()`` function must be used instead.
-Example::
+For example, in Python 3.10, it is no longer possible to use
+``Py_TYPE()`` as an l-value. The new ``Py_SET_TYPE()`` function must be
+used instead::
 
     #if PY_VERSION_HEX >= 0x030900A4
         Py_SET_TYPE(&MyType, &PyType_Type);
@@ -485,8 +484,8 @@ provides new C API functions to old Python versions. Example::
 Using this header file, ``Py_SET_TYPE()`` can be used on old Python
 versions as well.
 
-Developers can decide to copy this file in their project, or even to
-only copy/paste the few functions needed by the C extension.
+Developers can to copy this file in their project, or even to only
+copy/paste the few functions needed by their C extension.
 
 **STATUS**: In Progress (implemented but not shiped by CPython yet)
 
@@ -502,8 +501,8 @@ Process to introduce incompatible changes to the C API
   code for the future incompatible change.
 * Introduce the incompatible changes in Python. The documentation must
   explain how to port existing code. It is recommended to merge such
-  changes at the beginning of a development cycle to have more time to
-  test.
+  changes at the beginning of a development cycle to have more time for
+  tests.
 * Changes which are the most likely to break a large number of C
   extensions should be announced on the capi-sig mailing list to notify
   C extensions maintainers to prepare their project for the next Python.
@@ -515,14 +514,22 @@ The coordination usually means reporting issues to the projects, or even
 propose changes. It does not require waiting for a new release including
 fixes for every broken project.
 
+Since more and more C extensions are written using Cython, rather
+directly using the C API, it is important to ensure that Cython is
+prepared is advance for incompatible changes. It gives more time for C
+extension maintainers to release a new version with code generated with
+the updated Cython (for C extensions shipping the code generated by
+Cython).
+
 Future incompatible changes can be announced by deprecating a function
 in the documentation and by annotating the function with
-``Py_DEPRECATED()``. Making a structure opaque and preventing the usage
-of a macro as l-value cannot be deprecated with ``Py_DEPRECATED()``.
+``Py_DEPRECATED()``. But making a structure opaque and preventing the
+usage of a macro as l-value cannot be deprecated with
+``Py_DEPRECATED()``.
 
 The important part is coordination and balance the tradeoff between
 CPython evolutions and backward compatibility. For example, breaking a
-random old, obscure and unmaintained C extension on PyPI is less severe
+random, old, obscure and unmaintained C extension on PyPI is less severe
 than breaking numpy.
 
 If a change is reverted, we move back to the coordination step to better