PEP 605: Add example user-facing docs (#1200)
* PEP 605: Add example user-facing docs * example What's New subsection * example alpha, beta, and rc announcements * fix Python-Requires recommendation * add rationale for allowing mid-stream alpha releases * Stable ABI builds prior to 3.8 are also allowed * Alphas are also for application testing * Also put an ABI break marker in commit summaries
This commit is contained in:
Nick Coghlan
GitHub
parent
7cc2b15353
commit
8dbe669422
222
pep-0605.rst
222
pep-0605.rst
|
|
@ -123,6 +123,194 @@ by the publication of the first release candidate, and it will occur early
|
|||
enough to give publishers a couple of months to get ready for the final release.
|
||||
|
||||
|
||||
Example Future Release Announcements
|
||||
====================================
|
||||
|
||||
If this PEP is accepted, the primary channels used to communicate the updated
|
||||
pre-release management process to end users would be the Python 3.9 What's New
|
||||
document, and the release announcements themselves.
|
||||
|
||||
This section provides initial drafts of text that could be used for those
|
||||
purposes.
|
||||
|
||||
|
||||
Suggested "What's New in Python 3.9" Entry
|
||||
------------------------------------------
|
||||
|
||||
The following subsection would be added to the Python 3.9 What's New document,
|
||||
and then linked from each of the Python 3.9 alpha and beta announcements.
|
||||
|
||||
PEP 605: Changes to the pre-release management process
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
As detailed in PEP 605, the pre-release management process has been updated to
|
||||
produce a rolling series of beta releases that are considered suitable for
|
||||
production use in environments with sufficiently robust integration testing and
|
||||
operational monitoring capabilities.
|
||||
|
||||
Under this new rolling model, the alpha and beta releases are intermingled as
|
||||
part of a combined "pre-freeze" period, with alpha releases indicating breaks
|
||||
in the full CPython ABI that may require recompilation of extension modules or
|
||||
embedding applications, and beta releases indicating full binary compatibility
|
||||
with the immediately preceding pre-release.
|
||||
|
||||
Unlike previous releases, publishing pre-built binaries for 3.9.0 alpha and beta
|
||||
releases is actively encouraged, as a new pre-release ABI flag ("p") is now
|
||||
set when building and loading extension modules prior to the full CPython ABI
|
||||
freeze, ensuring that all such pre-freeze extension module builds will be
|
||||
ignored by post-freeze interpreter builds.
|
||||
|
||||
The full CPython ABI will be frozen, and the pre-release flag dropped from the
|
||||
ABI flags, in 3.9.0rc1, which is expected to occur 2 months prior to the final
|
||||
3.9.0 release (refer to the release schedule in PEP 596 for exact target dates).
|
||||
|
||||
For application developers, migrating to the rolling release stream provides
|
||||
the opportunity to be actively involved in the design and development of
|
||||
enhancements to the standard library and reference interpreter prior to the
|
||||
next stable release. It also provides the opportunity to benefit from
|
||||
interpreter performance enhancements up to a year or more before they become
|
||||
available in a stable release.
|
||||
|
||||
For library developers that publish pre-built wheel archives, opting in to
|
||||
supporting the 3.9.x rolling release stream in addition to the 3.8 stable
|
||||
release series requires no specific action if the project is already publishing
|
||||
either pure Python wheels (tagged as ``py3-none-any``), or builds against the
|
||||
stable C ABI (tagged as ``cp38-abi3-<platform>``, or the equivalent from an
|
||||
earlier CPython 3.x release). These same wheel archives will also be usable on
|
||||
the subsequent 3.9 stable release series.
|
||||
|
||||
For library developers that publish pre-built wheel archives that are built
|
||||
against the full CPython ABI, the binaries for the 3.9 stable release series
|
||||
will need to be built after the full CPython ABI freeze (i.e. using 3.9.0rc1 or
|
||||
later).
|
||||
|
||||
Developers of these libraries may also opt in to supporting the rolling release
|
||||
stream by building against the 3.9.0a1 release (or a subsequent beta release)
|
||||
and publishing the result as normal.
|
||||
|
||||
In the ideal case, binaries built this way will continue working all the way
|
||||
through to the last pre-freeze release. However, if the project is affected by
|
||||
a change in the full CPython C ABI during the pre-freeze period, then it will
|
||||
be necessary to publish a maintenance update that rebuilds the affected binaries
|
||||
against the alpha release that changed the relevant interface. In these cases,
|
||||
a corresponding ``Python-Requires`` entry should be added to the project
|
||||
metadata. For example, if a project is affected by an ABI change introduced in
|
||||
``3.9.0a5``, then the ``Python-Requires`` entry to add would be::
|
||||
|
||||
Python-Requires: >= "3.9.0b6"; python_version == "3.9" and full_python_version != "3.9.0a5"
|
||||
|
||||
(This additional metadata ensures that the updated version won't be installed on
|
||||
earlier pre-releases in the 3.9 series that offer an older variant of the ABI)
|
||||
|
||||
As for application developers, library developers that choose to support the
|
||||
rolling release stream will have the opportunity to provide feedback on new and
|
||||
updated API designs *before* they're locked down for multiple years in a stable
|
||||
release (or before they're included as a provisional API in a stable release
|
||||
series).
|
||||
|
||||
|
||||
Example announcement text for the 3.9.0a1 release
|
||||
-------------------------------------------------
|
||||
|
||||
This is the first preview release of Python 3.9. As an alpha release, it is
|
||||
intended for library and application compatibility testing and the creation of
|
||||
ABI compatible binary artifacts. It is not recommended for use in production
|
||||
environments.
|
||||
|
||||
Changes to the pre-release management process
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
CPython has switched to a new pre-release management process that is designed
|
||||
to produce a rolling series of beta releases that are considered suitable for
|
||||
production use in environments with sufficiently robust integration testing and
|
||||
operational monitoring capabilities. Refer to the Python 3.9 What's New
|
||||
document (hyperlinked to relevant section) for details.
|
||||
|
||||
Major new features of the 3.9 series, compared to 3.8
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Many new features for Python 3.9 are still being planned and written. Among the
|
||||
major new features and changes already implemented:
|
||||
|
||||
* ...
|
||||
* (Hey, fellow core developer or user of the rolling release stream, if a
|
||||
feature you find important is missing from this list, let <the release
|
||||
manager> know.)
|
||||
|
||||
The next pre-release of Python 3.9 is expected to be 3.8.0b2, currently scheduled for 2020-02-02.
|
||||
|
||||
|
||||
Example announcement text for the 3.9.0b2 release
|
||||
-------------------------------------------------
|
||||
|
||||
This is the second preview release of Python 3.9. As a beta release, it is
|
||||
fully binary compatible with the preceding 3.9.0a1 release. It is recommended
|
||||
for production use only in environments with sufficiently robust integration
|
||||
testing and operational monitoring capabilities.
|
||||
|
||||
(Remainder as per 3.9.0a1 announcement, with updates for implemented changes
|
||||
and the next expected release being 3.9.0b3)
|
||||
|
||||
|
||||
Example announcement text for 3.9.0a5 (a mid-stream alpha release)
|
||||
------------------------------------------------------------------
|
||||
|
||||
This is the fifth preview release of Python 3.9. As an alpha release, it is
|
||||
NOT fully binary compatible with the preceding 3.9.0b4 release. This release is
|
||||
intended for library and application compatibility testing and the creation of
|
||||
ABI compatible binary artifacts. It is not recommended for use in production
|
||||
environments.
|
||||
|
||||
Breaking changes in the full CPython ABI between 3.9.0b4 and 3.9.0a5
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
* new field ``ob_example`` added to the ``PyObject`` struct
|
||||
* provisional field ``tp_example`` removed from the ``PyTypeObject`` struct
|
||||
|
||||
Projects that are supporting the rolling release stream and require a rebuild
|
||||
to restore binary compatibility should add the following metadata to their
|
||||
updated release::
|
||||
|
||||
Python-Requires: >= "3.9.0b6"; python_version == "3.9" and full_python_version != "3.9.0a5"
|
||||
|
||||
(Remainder as per 3.9.0a1 announcement, with updates for implemented changes
|
||||
and the next expected release being 3.9.0b6)
|
||||
|
||||
Example announcement text for 3.9.0rc1
|
||||
--------------------------------------
|
||||
|
||||
This is the first release candidate for Python 3.9. As a release candidate,
|
||||
this release is now feature complete, the full CPython ABI is now frozen, and
|
||||
the pre-release marker has been removed from the ABI compatibility flags. It is
|
||||
recommended for production use only in environments with sufficiently robust
|
||||
integration testing and operational monitoring capabilities.
|
||||
|
||||
Preparation for the final 3.9.0 release
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
With the full CPython ABI now frozen, library developers targeting that ABI are
|
||||
encouraged to build and publish binaries for the stable 3.9.x series.
|
||||
|
||||
Application developers that have not been testing against the rolling release
|
||||
stream are encouraged to test their applications against the release candidate
|
||||
and report any compatibility regressions not already mentioned in the Porting
|
||||
Guide (hyperlinked to relevant What's New section).
|
||||
|
||||
A second release candidate is planned for 2021-07-02, and then the final 3.9.0
|
||||
release is planned for 2021-08-02.
|
||||
|
||||
|
||||
Major new features of the 3.9 series, compared to 3.8
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Some of the major new features and changes in this release:
|
||||
|
||||
* ...
|
||||
* (Hey, fellow core developer or user of the rolling release stream, if a
|
||||
feature you find important is missing from this list, let <the release
|
||||
manager> know.)
|
||||
|
||||
|
||||
Motivation
|
||||
==========
|
||||
|
||||
|
|
@ -467,8 +655,8 @@ Changes to management of the full CPython ABI
|
|||
|
||||
This PEP proposes two changes to the management of the full CPython ABI.
|
||||
|
||||
An explicit NEWS file convention to mark ABI breaking changes
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
An explicit commit and NEWS file convention to mark ABI breaking changes
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The proposal in this PEP requires that release managers be able to appropriately
|
||||
mark a pre-freeze release as either an alpha or a beta release based on whether
|
||||
|
|
@ -481,6 +669,16 @@ changes that introduce a breaking change in the full CPython C ABI.
|
|||
The "CPython" marker is included to make it clear that these annotations relate
|
||||
to the full CPython ABI, not the stable ABI.
|
||||
|
||||
For commit messages, the shorter marker "(ABI break)" would be placed at the
|
||||
start of the summary line for the commit.
|
||||
|
||||
The pre-merge bots will be updated to ensure that if the ABI break marker
|
||||
appears in one of the two locations, it appears in both of them.
|
||||
|
||||
If the marker is inadvertently omitted from the initial commit message and NEWS
|
||||
entry, then the commit message marker should be included in the subsequent
|
||||
commit that adds the marker to the NEWS entry.
|
||||
|
||||
In addition to being useful for release managers, these markers should also be
|
||||
useful for developers investigating unexpected segfaults when testing against
|
||||
the affected release.
|
||||
|
|
@ -550,11 +748,12 @@ a CPython ABI compatibility break in the 3.9.0a5 release, then they would add
|
|||
the following metadata entry on the version that published the updated binary
|
||||
build::
|
||||
|
||||
Python-Requires: >= "3.9.0a5"; python_version == "3.9"
|
||||
Python-Requires: >= "3.9.0b6"; python_version == "3.9" and full_python_version != "3.9.0a5"
|
||||
|
||||
What this does is add an additional compatibility constraint as part of the
|
||||
published packages, so Python 3.9.x versions older than 3.9.0a5 won't consider
|
||||
the updated package as a candidate for installation.
|
||||
published packages, so Python 3.9.0 beta versions prior to 3.9.0b6 won't
|
||||
consider the updated package as a candidate for installation, and the only
|
||||
alpha release that will consider the package is 3.9.0a5 itself.
|
||||
|
||||
|
||||
Caveats and Limitations
|
||||
|
|
@ -794,6 +993,19 @@ initially start out with a simple pre-release ABI flag, it would still be
|
|||
possible to devise a more sophisticated approach in the future.
|
||||
|
||||
|
||||
Why allow additional alpha releases after X.Y.0a1?
|
||||
--------------------------------------------------
|
||||
|
||||
In an ideal world, all breaking changes to the full CPython ABI would land in
|
||||
X.Y.0a1 alongside the filesystem layout changes, and the ABI for the release
|
||||
series would remain stable after that.
|
||||
|
||||
However, recent history doesn't suggest that we'd be able to actually make that
|
||||
commitment and stick to it, so the PEP assumes that ABI changes will be made
|
||||
progressively throughout the pre-freeze period, and the full lockdown will occur
|
||||
only with the creation of the X.Y.z maintenance branch when preparing X.Y.0rc1.
|
||||
|
||||
|
||||
Implications for CPython core development
|
||||
-----------------------------------------
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue