CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="color-scheme" content="light dark"> <title>PEP 608 – Coordinated Python release | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0608/"> <link rel="stylesheet" href="../_static/style.css" type="text/css"> <link rel="stylesheet" href="../_static/mq.css" type="text/css"> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light"> <link rel="stylesheet" href="../_static/pygments_dark.css" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark"> <link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss"> <meta property="og:title" content='PEP 608 – Coordinated Python release | peps.python.org'> <meta property="og:description" content="Block a Python release until a compatible version of selected projects is available."> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0608/"> <meta property="og:site_name" content="Python Enhancement Proposals (PEPs)"> <meta property="og:image" content="https://peps.python.org/_static/og-image.png"> <meta property="og:image:alt" content="Python PEPs"> <meta property="og:image:width" content="200"> <meta property="og:image:height" content="200"> <meta name="description" content="Block a Python release until a compatible version of selected projects is available."> <meta name="theme-color" content="#3776ab"> </head> <body> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all"> <title>Following system colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="9"></circle> <path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path> </svg> </symbol> <symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all"> <title>Selected dark colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <path stroke="none" d="M0 0h24v24H0z" fill="none"></path> <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path> </svg> </symbol> <symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all"> <title>Selected light colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="5"></circle> <line x1="12" y1="1" x2="12" y2="3"></line> <line x1="12" y1="21" x2="12" y2="23"></line> <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line> <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line> <line x1="1" y1="12" x2="3" y2="12"></line> <line x1="21" y1="12" x2="23" y2="12"></line> <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line> <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line> </svg> </symbol> </svg> <script> document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto" </script> <section id="pep-page-section"> <header> <h1>Python Enhancement Proposals</h1> <ul class="breadcrumbs"> <li><a href="https://www.python.org/" title="The Python Programming Language">Python</a> » </li> <li><a href="../pep-0000/">PEP Index</a> » </li> <li>PEP 608</li> </ul> <button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())"> <svg aria-hidden="true" class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg> <span class="visually-hidden">Toggle light / dark / auto colour theme</span> </button> </header> <article> <section id="pep-content"> <h1 class="page-title">PEP 608 – Coordinated Python release</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author<span class="colon">:</span></dt> <dd class="field-odd">Miro Hrončok <miro at hroncok.cz>, Victor Stinner <vstinner at python.org></dd> <dt class="field-even">Status<span class="colon">:</span></dt> <dd class="field-even"><abbr title="Formally declined and will not be accepted">Rejected</abbr></dd> <dt class="field-odd">Type<span class="colon">:</span></dt> <dd class="field-odd"><abbr title="Normative PEP with a new feature for Python, implementation change for CPython or interoperability standard for the ecosystem">Standards Track</abbr></dd> <dt class="field-even">Created<span class="colon">:</span></dt> <dd class="field-even">25-Oct-2019</dd> <dt class="field-odd">Python-Version<span class="colon">:</span></dt> <dd class="field-odd">3.9</dd> </dl> <hr class="docutils" /> <section id="contents"> <details><summary>Table of Contents</summary><ul class="simple"> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#rationale">Rationale</a><ul> <li><a class="reference internal" href="#too-few-projects-are-involved-in-the-python-beta-phase">Too few projects are involved in the Python beta phase</a></li> <li><a class="reference internal" href="#deprecationwarning-is-being-ignored">DeprecationWarning is being ignored</a></li> <li><a class="reference internal" href="#need-to-coordinate">Need to coordinate</a></li> <li><a class="reference internal" href="#shorter-python-release-schedule">Shorter Python release schedule</a></li> </ul> </li> <li><a class="reference internal" href="#specification">Specification</a><ul> <li><a class="reference internal" href="#limit-the-delay">Limit the delay</a></li> <li><a class="reference internal" href="#selected-projects">Selected projects</a></li> <li><a class="reference internal" href="#how-projects-are-selected">How projects are selected</a></li> </ul> </li> <li><a class="reference internal" href="#incompatible-changes">Incompatible changes</a><ul> <li><a class="reference internal" href="#examples">Examples</a></li> <li><a class="reference internal" href="#cleaning-up-python-and-deprecationwarning">Cleaning up Python and DeprecationWarning</a></li> </ul> </li> <li><a class="reference internal" href="#distributed-ci">Distributed CI</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> </details></section> <section id="abstract"> <h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2> <p>Block a Python release until a compatible version of selected projects is available.</p> <p>The Python release manager can decide to release Python even if a project is not compatible, if they decide that the project is going to be fixed soon enough, or if the issue severity is low enough.</p> </section> <section id="rationale"> <h2><a class="toc-backref" href="#rationale" role="doc-backlink">Rationale</a></h2> <p>The PEP involves maintainers of the selected projects in the Python release cycle. There are multiple benefit:</p> <ul class="simple"> <li>Detect more bugs before a Python final release</li> <li>Discuss and maybe revert incompatible changes before a Python final release</li> <li>Increase the number of compatible projects when the new Python final version is released</li> </ul> <section id="too-few-projects-are-involved-in-the-python-beta-phase"> <h3><a class="toc-backref" href="#too-few-projects-are-involved-in-the-python-beta-phase" role="doc-backlink">Too few projects are involved in the Python beta phase</a></h3> <p>Currently, Python beta versions are available four months before the final 3.x.0 release.</p> <p>Bugs reported during the beta phase can be easily fixed and can block a release if they are serious enough.</p> <p>Incompatible changes are discussed during the beta phase: enhance documentation explaining how to update code, or consider to revert these changes.</p> <p>Even if more and more projects are tested on the master branch of Python in their CI, too many projects of the top 50 PyPI projects are only compatible with the new Python a few weeks, or even months, after the final Python release.</p> </section> <section id="deprecationwarning-is-being-ignored"> <h3><a class="toc-backref" href="#deprecationwarning-is-being-ignored" role="doc-backlink">DeprecationWarning is being ignored</a></h3> <p>Python has well defined process to deprecate features. A DeprecationWarning must be emitted during at least one Python release, before a feature can be removed.</p> <p>In practice, DeprecationWarning warnings are ignored for years in major Python projects. Usually, maintainers explain that there are too many warnings and so they simply ignore warnings. Moreover, DeprecationWarning is silent by default (except in the <code class="docutils literal notranslate"><span class="pre">__main__</span></code> module: <a class="pep reference internal" href="../pep-0565/" title="PEP 565 – Show DeprecationWarning in __main__">PEP 565</a>).</p> <p>Even if more and more projects are running their test suite with warnings treated as errors (<code class="docutils literal notranslate"><span class="pre">-Werror</span></code>), Python core developers still have no idea how many projects are broken when a feature is removed.</p> </section> <section id="need-to-coordinate"> <h3><a class="toc-backref" href="#need-to-coordinate" role="doc-backlink">Need to coordinate</a></h3> <p>When issues and incompatible changes are discovered and discussed after the final Python release, it becomes way more complicated and expensive to fix Python. Once an API is part of an official final release, Python should provide backward compatibility for the whole 3.x release lifetime. Some operating systems can be shipped with the buggy final release and can take several months before being updated.</p> <p>Too many projects are only updated to the new Python after the final Python release, which makes this new Python version barely usable to run large applications when Python is released.</p> <p>It is proposed to block a Python release until a compatible version of all selected projects is available.</p> </section> <section id="shorter-python-release-schedule"> <h3><a class="toc-backref" href="#shorter-python-release-schedule" role="doc-backlink">Shorter Python release schedule</a></h3> <p>The <a class="pep reference internal" href="../pep-0602/" title="PEP 602 – Annual Release Cycle for Python">PEP 602: Annual Release Cycle for Python</a> and the <a class="pep reference internal" href="../pep-0605/" title="PEP 605 – A rolling feature release stream for CPython">PEP 605: A rolling feature release stream for CPython</a> would like to release Python more often to ship new features more quickly.</p> <p>The problem is that each Python <code class="docutils literal notranslate"><span class="pre">3.x</span></code> release breaks many projects.</p> <p>Coordinated Python releases reduces the number of broken projects and makes new Python release more usable.</p> </section> </section> <section id="specification"> <h2><a class="toc-backref" href="#specification" role="doc-backlink">Specification</a></h2> <p>By default, a Python release is blocked until a compatible version of all selected projects is available.</p> <p>Before releasing the final Python version, the Python release manager is responsible to send a report of the compatibility status of each project of the selected projects. It is recommended to send such report at each beta release to see the evolution and detects issues as soon as possible.</p> <p>The Python release manager can decide to release Python even if a project is not compatible, if they decide that the project is going to be fixed soon enough, or if the issue severity is low enough.</p> <p>After each Python release, the project list can be updated to remove projects and add new ones. For example, to remove old unused dependencies and add new ones. The list can grow if the whole process doesn’t block Python releases for too long.</p> <section id="limit-the-delay"> <h3><a class="toc-backref" href="#limit-the-delay" role="doc-backlink">Limit the delay</a></h3> <p>When a build or test issue with the next Python version is reported to a project, maintainers have one month to answer. With no answer, the project can be excluded from the list of projects blocking the Python release.</p> <p>Multiple projects are already tested on the master branch of Python in a CI. Problems can be detected very early in a Python release which should provide enough time to handle them. More CI can be added for projects which are not tested on the next Python yet.</p> <p>Once selected projects issues are known, exceptions can be discussed between the Python release manager and involved project maintainers on a case-by-case basis. Not all issues deserve to block a Python release.</p> </section> <section id="selected-projects"> <h3><a class="toc-backref" href="#selected-projects" role="doc-backlink">Selected projects</a></h3> <p>List of projects blocking a Python release (total: 27):</p> <ul class="simple"> <li>Projects (13):<ul> <li>aiohttp</li> <li>cryptography</li> <li>Cython</li> <li>Django</li> <li>numpy</li> <li>pandas</li> <li>pip</li> <li>requests</li> <li>scipy</li> <li>Sphinx (needed to build Python)</li> <li>sqlalchemy</li> <li>pytest</li> <li>tox</li> </ul> </li> <li>Direct and indirect dependencies (14):<ul> <li>certifi (needed by urllib3)</li> <li>cffi (needed by cryptography)</li> <li>chardet (needed by Sphinx)</li> <li>colorama (needed by pip)</li> <li>docutils (needed by Sphinx)</li> <li>idna (needed by Sphinx and requests)</li> <li>jinja2 (needed by Sphinx)</li> <li>MarkupSafe (needed by Sphinx)</li> <li>psycopg2 (needed by Django)</li> <li>pycparser (needed by cffi)</li> <li>setuptools (needed by pip and tons of Python projects)</li> <li>six (needed by tons of Python projects)</li> <li>urllib3 (needed by requests)</li> <li>wheel (needed by pip)</li> </ul> </li> </ul> </section> <section id="how-projects-are-selected"> <h3><a class="toc-backref" href="#how-projects-are-selected" role="doc-backlink">How projects are selected</a></h3> <p>Projects used by to build Python should be in the list, like Sphinx.</p> <p>Most popular projects are picked from the most downloaded PyPI projects.</p> <p>Most of project dependencies are included in the list as well, since a single incompatible dependency can block a whole project. Some dependencies are excluded to reduce the list length.</p> <p>Test dependencies as pytest and tox should be included as well. If a project cannot be tested, a new version cannot be shipped neither.</p> <p>The list should be long enough to have a good idea of the cost of porting a project to the next Python, but small enough to not block a Python release for too long.</p> <p>Obviously, projects which are not part of the list also are encouraged to report issues with the next Python and to have a CI running on the next Python version.</p> </section> </section> <section id="incompatible-changes"> <h2><a class="toc-backref" href="#incompatible-changes" role="doc-backlink">Incompatible changes</a></h2> <p>The definition here is large: any Python change which cause an issue when building or testing a project.</p> <p>See also the <a class="pep reference internal" href="../pep-0606/" title="PEP 606 – Python Compatibility Version">PEP 606: Python Compatibility Version</a> for more examples of incompatible changes.</p> <section id="examples"> <h3><a class="toc-backref" href="#examples" role="doc-backlink">Examples</a></h3> <p>There are different kinds of incompatible changes:</p> <ul class="simple"> <li>Change in the Python build. For example, Python 3.8 removed <code class="docutils literal notranslate"><span class="pre">'m'</span></code> (which stands for pymalloc) from <code class="docutils literal notranslate"><span class="pre">sys.abiflags</span></code> which impacts Python vendors like Linux distributions.</li> <li>Change in the C extensions build. For example, Python 3.8 no longer links C extensions to libpython, and Python 3.7 removed <code class="docutils literal notranslate"><span class="pre">os.errno</span></code> alias to the <code class="docutils literal notranslate"><span class="pre">errno</span></code> module.</li> <li>Removed function. For example, collections aliases to ABC classes have been removed in Python 3.9.</li> <li>Changed function signature:<ul> <li>Reject a type which was previously accepted (ex: only accept <code class="docutils literal notranslate"><span class="pre">int</span></code>, reject <code class="docutils literal notranslate"><span class="pre">float</span></code>).</li> <li>Add a new mandatory parameter.</li> <li>Convert a positional-or-keyword parameter to positional-only.</li> </ul> </li> <li>Behavior change. For example, Python 3.8 now serializes XML attributes in their insertion order, rather than sorting them by name.</li> <li>New warning. Since more and more projects are tested with all warnings treated as errors, any new warning can cause a project test to fail.</li> <li>Function removed from the C API.</li> <li>Structure made opaque in the C API. For example, PyInterpreterState became opaque in Python 3.8 which broke projects accessing <code class="docutils literal notranslate"><span class="pre">interp->modules</span></code> (<code class="docutils literal notranslate"><span class="pre">PyImport_GetModuleDict()</span></code> should be used instead).</li> </ul> </section> <section id="cleaning-up-python-and-deprecationwarning"> <h3><a class="toc-backref" href="#cleaning-up-python-and-deprecationwarning" role="doc-backlink">Cleaning up Python and DeprecationWarning</a></h3> <p>One of the <a class="pep reference internal" href="../pep-0020/" title="PEP 20 – The Zen of Python">Zen of Python (PEP 20)</a> motto is:</p> <blockquote> <div>There should be one– and preferably only one –obvious way to do it.</div></blockquote> <p>When Python evolves, new ways emerge inevitably. <code class="docutils literal notranslate"><span class="pre">DeprecationWarning</span></code> are emitted to suggest to use the new way, but many developers ignore these warnings which are silent by default.</p> <p>Sometimes, supporting both ways has a minor maintenance cost, but Python core developers prefer to drop the old way to clean up the Python code base and standard library. Such kind of change is backward incompatible.</p> <p>More incompatible changes than usual should be expected with the end of the Python 2 support which is a good opportunity to cleaning up old Python code.</p> </section> </section> <section id="distributed-ci"> <h2><a class="toc-backref" href="#distributed-ci" role="doc-backlink">Distributed CI</a></h2> <p>Checking if selected projects are compatible with the master branch of Python can be automated using a distributed CI.</p> <p>Existing CIs can be reused.</p> <p>New CIs can be added for projects which are not tested on the next Python yet.</p> <p>It is recommended to treat DeprecationWarning warnings as errors when testing on the next Python.</p> <p>A job testing a project on the next Python doesn’t have to be “mandatory” (block the whole CI). It is fine to have failures during the beta phase of a Python release. The job only has to pass for the final Python release.</p> </section> <section id="copyright"> <h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2> <p>This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.</p> </section> </section> <hr class="docutils" /> <p>Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0608.rst">https://github.com/python/peps/blob/main/peps/pep-0608.rst</a></p> <p>Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0608.rst">2023-09-09 17:39:29 GMT</a></p> </article> <nav id="pep-sidebar"> <h2>Contents</h2> <ul> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#rationale">Rationale</a><ul> <li><a class="reference internal" href="#too-few-projects-are-involved-in-the-python-beta-phase">Too few projects are involved in the Python beta phase</a></li> <li><a class="reference internal" href="#deprecationwarning-is-being-ignored">DeprecationWarning is being ignored</a></li> <li><a class="reference internal" href="#need-to-coordinate">Need to coordinate</a></li> <li><a class="reference internal" href="#shorter-python-release-schedule">Shorter Python release schedule</a></li> </ul> </li> <li><a class="reference internal" href="#specification">Specification</a><ul> <li><a class="reference internal" href="#limit-the-delay">Limit the delay</a></li> <li><a class="reference internal" href="#selected-projects">Selected projects</a></li> <li><a class="reference internal" href="#how-projects-are-selected">How projects are selected</a></li> </ul> </li> <li><a class="reference internal" href="#incompatible-changes">Incompatible changes</a><ul> <li><a class="reference internal" href="#examples">Examples</a></li> <li><a class="reference internal" href="#cleaning-up-python-and-deprecationwarning">Cleaning up Python and DeprecationWarning</a></li> </ul> </li> <li><a class="reference internal" href="#distributed-ci">Distributed CI</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> <br> <a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0608.rst">Page Source (GitHub)</a> </nav> </section> <script src="../_static/colour_scheme.js"></script> <script src="../_static/wrap_tables.js"></script> <script src="../_static/sticky_banner.js"></script> </body> </html>