PEP 689: Rename to "Unstable C API tier" (#2576)

Co-authored-by: Adam Turner <[email protected]>

Author: encukou

pep-0689.rst

@@ -1,5 +1,5 @@
 PEP: 689
-Title: Semi-stable C API tier
+Title: Unstable C API tier
 Author: Petr Viktorin <[email protected]>
 Status: Draft
 Type: Standards Track
@@ -13,7 +13,7 @@ Post-History: `27-Apr-2022 <https://mail.python.org/archives/list/python-dev@pyt
 Abstract
 ========
 
-Some functions and types of the C-API are designated *semi-stable*,
+Some functions and types of the C-API are designated *unstable*,
 meaning that they will not change in patch (bugfix/security) releases,
 but may change between minor releases (e.g. between 3.11 and 3.12) without
 deprecation warnings.
@@ -29,9 +29,12 @@ The Python C-API is currently divided into `three tiers <https://devguide.python
   <387>`, and requires deprecation warnings before changes
 - Private (internal) API, which can change at any time.
 
-We need a tier between Public and Private to accommodate tools like
-advanced debuggers and JIT compilers, which need access to CPython
-internals but assume the C-API they use does not change in patch releases.
+Tools requring access to CPython internals (e.g. advanced
+debuggers and JIT compilers) are often built for minor series releases
+of CPython, and assume that the C-API internals used do not change
+in patch releases. To support these tools, we need a tier between the
+Public and Private C-API, with guarantees on stability throughout
+the minor-series release.
 
 
 Setting Stability Expectations
@@ -49,7 +52,7 @@ in patch releases:
 - Patch releases only contain bugfixes, which are unlikely to
   change the API.
 
-Semi-stable API will make the stability expectations more explicit.
+Unstable API will make the stability expectations more explicit.
 
 It will also hopefully encourage existing users of the private API to
 reach out to python-dev, so we can expose, standardize and test an API
@@ -70,16 +73,17 @@ convention are unlikely to check if underscored functions they are
 changing are documented and used outside CPython itself.
 
 This proposal brings us a bit closer to reserving underscores
-only for truly private, unstable, hands-off API.
+only for truly internal, private, hands-off API.
 
 
 Warning about API that is changed often
 ---------------------------------------
 
 The ``PyCode_New()`` family is an example of functions that are
-documented as unstable, and also often change in practice.
+documented as unstable (“Calling [it] directly can bind you to a precise
+Python version”), and also often change in practice.
 
-Moving it to the semi-stable tier will make its status obvious even
+Moving it to the unstable tier will make its status obvious even
 to people who don't read the docs carefully enough, and will make it
 hard to use accidentally.
 
@@ -90,16 +94,16 @@ Changes during the Beta period
 Since the API itself can change continuously up until Beta 1 (feature freeze)
 of a minor version, major users of this API are unlikely to test
 Alpha releases and provide feedback.
-It is very difficult to determine what needs to be exposed as semi-stable.
+It is very difficult to determine what needs to be exposed as unstable.
 
-Additions to the semi-stable tier will count as *stabilization*,
+Additions to the unstable tier will count as *stabilization*,
 and will be allowed up to Release Candidate 1.
 
 
 Specification
 =============
 
-Several functions and types (“APIs”) will be moved to a new *semi-stable* tier.
+Several functions and types (“APIs”) will be moved to a new *unstable* tier.
 
 They will be expected to stay stable across patch releases,
 but may change or be removed without warning in minor releases (3.x.0),
@@ -109,20 +113,20 @@ When they change significantly, code that uses them should no longer compile
 (e.g. arguments should be added/removed, or a function should be renamed,
 but the semantic meaning of an argument should not change).
 
-Their definitions will be moved to a new directory, ``Include/semistable/``,
+Their definitions will be moved to a new directory, ``Include/unstable/``,
 and will be included from ``Python.h``.
 
 From Python 3.12 on, these APIs will only be usable when the
-``Py_USING_SEMI_STABLE_API`` macro is defined.
+``Py_USING_UNSTABLE_API`` macro is defined.
 CPython will only define the macro for building CPython itself
 (``Py_BUILD_CORE``).
 
-To make transition to semi-stable API easier,
-in Python 3.11 the APIs will be available without ``Py_USING_SEMI_STABLE_API``
+To make transition to unstable API easier,
+in Python 3.11 the APIs will be available without ``Py_USING_UNSTABLE_API``
 defined. In this case, using them will generate a deprecation warning on
 compilers that support ``Py_DEPRECATED``.
 
-A similar deprecation period will be used when making more APIs semi-stable
+A similar deprecation period will be used when making more APIs unstable
 in the future:
 
 - When moving from public API, the deprecation period should follow Python's
@@ -137,25 +141,25 @@ Leading underscores will be removed from the names of the moved APIs.
 The old underscored name of a renamed API will be available (as an alias
 using ``#define``) at least until that API changes.
 
-The semi-stable C-API tier and ``Py_USING_SEMI_STABLE_API`` will be documented,
-and documentation of each semi-stable API will be updated.
+The unstable C-API tier and ``Py_USING_UNSTABLE_API`` will be documented,
+and documentation of each unstable API will be updated.
 
 
 Adjustments during Beta periods
 -------------------------------
 
-New APIs can be added to the semi-stable tier, and private APIs can be moved
+New APIs can be added to the unstable tier, and private APIs can be moved
 to it, up to the first release candidate of a new minor version.
 Consensus on the ``capi-sig`` or ``python-dev`` is needed in the Beta period.
 
 In the Beta period, no API may be moved to more private tier, e.g.
 what is public in Beta 1 must stay public until the final release.
 
 
-Initial semi-stable API
------------------------
+Initial unstable API
+--------------------
 
-The following API will initially be semi-stable.
+The following API will initially be unstable.
 The set may be adjusted for 3.11.
 
 Code object constructors:
@@ -211,9 +215,7 @@ This is outside the scope of the PEP.
 Open Issues
 ===========
 
-- “Semi-stable” is not a perfect name.
-
-- The exact set of exposed API may change.
+The exact set of exposed API may change.
 
 
 Copyright