From 26715b08f56a617405bf32e892cccaa68b557e00 Mon Sep 17 00:00:00 2001
From: Petr Viktorin <encukou@gmail.com>
Date: Wed, 4 May 2022 00:40:32 +0200
Subject: [PATCH 1/3] PEP 689: Rename to "Unstable C API tier"

---
 pep-0689.rst | 45 ++++++++++++++++++++++-----------------------
 1 file changed, 22 insertions(+), 23 deletions(-)

diff --git a/pep-0689.rst b/pep-0689.rst
index 67eb6f801f8..0513ddcfd21 100644
--- a/pep-0689.rst
+++ b/pep-0689.rst
@@ -1,5 +1,5 @@
 PEP: 689
-Title: Semi-stable C API tier
+Title: Unstable C API tier
 Author: Petr Viktorin <encukou@gmail.com>
 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.
@@ -49,7 +49,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 +70,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 +91,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 +110,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,14 +138,14 @@ 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.
 
@@ -152,10 +153,10 @@ 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 +212,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

From 57959e5e09ca2328924a664cdfebdcdc106222a7 Mon Sep 17 00:00:00 2001
From: Petr Viktorin <encukou@gmail.com>
Date: Wed, 4 May 2022 00:48:03 +0200
Subject: [PATCH 2/3] Improve wording in Rationale as suggested by AA-Turner

> The current wording is in the rationale section, which is
> setting out the justification for the proposal. To me, it
> seems odd to phrase it "We need <feature> because <thing>
> requires <requirement>, but we don't guarantee requirement.
>
> My suggested rephrasing more explicity spells out that we
> want to support <thing> properly, there is a reason the
> current state doesn't work (no guarantees at an API level
> of stability), and hence <feature> is needed that provides
> those guarantees.

- https://github.com/python/peps/pull/2559#discussion_r860177857
---
 pep-0689.rst | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/pep-0689.rst b/pep-0689.rst
index 0513ddcfd21..707923ffa9f 100644
--- a/pep-0689.rst
+++ b/pep-0689.rst
@@ -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 interals 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

From 94f8ee8cd88a5aee3113c55171baf19855b27e8d Mon Sep 17 00:00:00 2001
From: Petr Viktorin <encukou@gmail.com>
Date: Wed, 4 May 2022 09:24:23 +0200
Subject: [PATCH 3/3] Update pep-0689.rst

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
---
 pep-0689.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pep-0689.rst b/pep-0689.rst
index 707923ffa9f..adaaeef76c0 100644
--- a/pep-0689.rst
+++ b/pep-0689.rst
@@ -31,7 +31,7 @@ The Python C-API is currently divided into `three tiers <https://devguide.python
 
 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 interals used do not change
+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.