Update Guide to 56cd973

Signed-off-by: Michał Górny <mgorny@gentoo.org>

2 files changed, 100 insertions, 72 deletions

diff --git a/guide/_sources/interpreter-maintenance.rst.txt b/guide/_sources/interpreter-maintenance.rst.txt
index 80f1ea2..eb0da59 100644
--- a/guide/_sources/interpreter-maintenance.rst.txt
+++ b/guide/_sources/interpreter-maintenance.rst.txt
@@ -2,77 +2,6 @@
 Maintenance of Python implementations
 =====================================
 
-Life cycle of a Python implementation
-=====================================
-Every Python implementation (understood as a potential target) in Gentoo
-follows roughly the following life cycle:
-
-1. The interpreter is added to ``~arch`` for initial testing.  At this
-   point, packages can not declare support for the implementation yet.
-
-2. The new Python target is added.  It is initially stable-masked,
-   so only ``~arch`` users can use it.  At this point, packages start
-   being tested against the new target and its support starts being
-   declared in ``PYTHON_COMPAT``.
-
-3. When ready, the new interpreter is stabilized.  The target is not yet
-   available for stable users, though.
-
-4. The stable-mask for the target is removed.  For this to happen,
-   the inconsistencies in stable graph need to be addressed first
-   via stabilizing newer versions of packages.
-
-5. Over time, developers are repeatedly asked to push testing packages
-   for the new target forward and stabilize new versions supporting it.
-   Eventually, the final push for updates happens and packages
-   not supporting the new target start being removed.
-
-6. If applicable, the new target becomes the default.  The developers
-   are required to test new packages against it.  The support for old
-   target is slowly being discontinued.
-
-7. Eventually, the target becomes replaced by the next one.  When it
-   nears end of life, the final packages requiring it are masked for
-   removal and the target flags are disabled.
-
-8. The compatibility declarations are cleaned up from ``PYTHON_COMPAT``
-   and obsolete ebuild and eclass code is cleaned up.
-
-9. Finally, the interpreter is moved to `python repository`_ where it
-   lives for as long as it builds.
-
-For example, Python 3.9 is at stage 1 at the time of writing.  It is
-still in alpha stage, and upstream has not finalized its feature set,
-therefore it is too early to declare package support for Python 3.9
-and there are no target flags.
-
-Python 3.8 is moving from stage 2 to stage 3 — it is being stabilized
-by arch teams at this very moment.  When that's done, we will work
-on unmasking the flag on stable systems and it will become our next
-default target.
-
-Python 3.7 is moving from stage 5 to stage 6.  The vast majority
-of packages have been ported to it, and we have already announced
-the switch date.
-
-When the switch happens, Python 3.6 will move from stage 6 to stage 7.
-We are going to support it for quite some time still but as things
-progress, we will eventually decide to remove it.
-
-Python 3.5 and 3.4 are at stage 9.  They live in the Python repository
-but have no targets.  You can still use them e.g. inside a virtualenv
-to test your own software.
-
-Python 2.7 is currently somewhere between stages 6 and 7.  It is still
-enabled by default for backwards compatibility but we are aggressively
-removing it.
-
-PyPy3 has recently reached stage 3.  It is not clear if we are going
-to pursue enabling the target on stable system though.  PyPy2.7 is
-at stage 8, as the targets were removed already and it is kept
-as a dependency and testing target.
-
-
 Notes specific to Python interpreters
 =====================================
 CPython patchsets
@@ -323,7 +252,6 @@ Its author indicates in the `flit_core vendoring README`_ that no other
 dependencies will be added or vendored into flit_core.
 
 
-.. _python repository: https://gitweb.gentoo.org/proj/python.git/
 .. _Gentoo fork of CPython repository:
    https://gitweb.gentoo.org/fork/cpython.git/
 .. _Docker: https://www.docker.com/
diff --git a/guide/_sources/interpreter.rst.txt b/guide/_sources/interpreter.rst.txt
index 81111a3..272b463 100644
--- a/guide/_sources/interpreter.rst.txt
+++ b/guide/_sources/interpreter.rst.txt
@@ -38,6 +38,106 @@ window of 3-4 versions of Python 3.  They are provided as slots
 of ``dev-lang/python``.
 
 
+Life cycle of a Python implementation
+=====================================
+Every Python implementation (understood as a potential target) in Gentoo
+follows roughly the following life cycle:
+
+1. The interpreter is added to ``~arch`` for initial testing.  At this
+   point, packages can not declare support for the implementation yet.
+
+   New CPython releases enter this stage when upstream releases
+   the first alpha version.  Since the feature set is not stable yet,
+   it is premature to declare the package compatibility with these
+   versions.
+
+2. The new Python target is added.  It is initially stable-masked,
+   so only ``~arch`` users can use it.  At this point, packages start
+   being tested against the new target and its support starts being
+   declared in ``PYTHON_COMPAT``.
+
+   CPython releases enter this stage when the first beta release
+   is made.  These versions are not fully stable yet either and package
+   regressions do happen between beta releases but they are stable
+   enough for initial testing.
+
+3. When ready, the new interpreter is stabilized.  The target is not yet
+   available for stable users, though.
+
+   CPython releases enter this stage roughly 30 days after the first
+   stable release (i.e. X.Y.0 final) is made.  This is also the stage
+   where PyPy3 releases are in Gentoo for the time being.
+
+4. The stable-mask for the target is removed.  For this to happen,
+   the inconsistencies in stable graph need to be addressed first
+   via stabilizing newer versions of packages.
+
+   CPython releases enter this stage after the interpreter is marked
+   stable on all architectures and all the packages needed to clear
+   the stable depenendency graph are stable as well.
+
+5. Over time, developers are repeatedly asked to push testing packages
+   for the new target forward and stabilize new versions supporting it.
+   Eventually, the final push for updates happens and packages
+   not supporting the new target start being removed.
+
+6. If applicable, the new target becomes the default.  The developers
+   are required to test new packages against it.  The support for old
+   target is slowly being discontinued.
+
+   Currently, we try to plan the switch to the next CPython version
+   around June — July every year, to make these events more predictable
+   to Gentoo users.
+
+7. Eventually, the target becomes replaced by the next one.  When it
+   nears end of life, the final packages requiring it are masked for
+   removal and the target flags are disabled.
+
+   We generally aim to preserve support for old targets for as long
+   as they are found still needed by Gentoo users.  However, as more
+   upstream packages remove support for older versions of Python,
+   the cost of preserving the support becomes too great.
+
+8. The compatibility declarations are cleaned up from ``PYTHON_COMPAT``,
+   and obsolete ebuild and eclass code is cleaned up.
+
+9. Finally, the interpreter is removed when it becomes no longer
+   feasible to maintain it (usually because of the cost of fixing
+   vulnerabilities or build failures).
+
+
+Stability guarantees of Python implementations
+==============================================
+The language and standard library API of every Python version is
+expected to be stable since the first beta release of the matching
+CPython version.  However, historically there were cases of breaking
+changes prior to a final release (e.g. the revert of ``enum`` changes
+in Python 3.10), as well as across minor releases (e.g. ``urlsplit()``
+URL sanitization / security fix).
+
+The ABI of every CPython version is considered stable across bugfix
+releases since the first RC.  This includes the public ABI of libpython,
+C extensions and compiled Python modules.  Prior to the first RC,
+breaking changes to either may still happen.  Gentoo currently does not
+account for these changes to the high cost of using slot operators,
+and therefore users using ``~arch`` CPython may have to occasionally
+rebuild Python packages manually.
+
+Additionally, modern versions of CPython declare so-called 'stable ABI'
+that remains forward compatible across Python versions.  This permits
+upstreams to release wheels that can be used with multiple CPython
+versions (contrary to the usual case of building wheels separately
+for each version).  However, this does not affect Gentoo packaging
+at the moment.
+
+PyPy does not hold specific ABI stability guarantees.  Gentoo packages
+use subslots to declare the current ABI version, and the eclasses use
+slot operators in dependencies to enforce rebuilds whenever the ABI
+version changes.  Fortunately, lately this has only occurred whenever
+Gentoo switched to the next PyPy branch (i.e. the one corresponding
+to the next Python language version).
+
+
 Alternative Python implementations
 ==================================
 CPython is the reference and most commonly used Python implementation.