Following system colour scheme Selected dark colour scheme Selected light colour scheme

Python Enhancement Proposals

PEP 101 – Doing Python Releases 101

Author:
Barry Warsaw <barry at python.org>, Guido van Rossum <guido at python.org>
Status:
Active
Type:
Informational
Created:
22-Aug-2001
Post-History:

Replaces:
102
Table of Contents

Abstract

Making a Python release is a thrilling and crazy process. You’ve heard the expression “herding cats”? Imagine trying to also saddle those purring little creatures up, and ride them into town, with some of their buddies firmly attached to your bare back, anchored by newly sharpened claws. At least they’re cute, you remind yourself.

Actually, no, that’s a slight exaggeration 😉 The Python release process has steadily improved over the years and now, with the help of our amazing community, is really not too difficult. This PEP attempts to collect, in one place, all the steps needed to make a Python release. Most of the steps are now automated or guided by automation, so manually following this list is no longer necessary.

Things You’ll Need

As a release manager there are a lot of resources you’ll need to access. Here’s a hopefully-complete list.

  • A GPG key.

    Python releases before 3.14 are digitally signed with GPG; for these you’ll need a key, which hopefully will be on the “web of trust” with at least one of the other release managers.

    Note

    GPG instructions in this PEP can be ignored for Python 3.14 and later. See PEP 761 for details.

  • A bunch of software:
    • A checkout of the python/release-tools repo. It contains a requirements.txt file that you need to install dependencies from first. Afterwards, you can fire up scripts in the repo, covered later in this PEP.
    • blurb, the Misc/NEWS management tool. You can pip install it.
  • Access to servers where you will upload files:
    • downloads.nyc1.psf.io, the server that hosts download files; and
    • docs.nyc1.psf.io, the server that hosts the documentation.
  • Administrator access to python/cpython and membership of the Release Managers team.
  • An administrator account on www.python.org, including an “API key”.
  • Write access to the python/peps repository.

    If you’re reading this, you probably already have this–the first task of any release manager is to draft the release schedule. But in case you just signed up… sucker! I mean, uh, congratulations!

  • A subscription to the super secret release manager mailing list, which may or may not be called python-cabal. Bug Barry about this.
  • A @python.org email address that you will use to sign your releases with. Ask postmaster@ for an address; you can either get a full account, or a redirecting alias + SMTP credentials to send email from this address that looks legit to major email providers.
  • Be added to the Python Security Response Team.

Types of Releases

There are several types of releases you will need to make. These include:

  • alpha
  • begin beta, also known as beta 1, also known as new branch
  • beta 2+
  • release candidate 1
  • release candidate 2+
  • final
  • new branch
  • begin bugfix mode
  • begin security-only mode
  • end-of-life

Some of these release types actually involve more than one release branch. In particular, a new branch is that point in the release cycle when a new feature release cycle begins. Under the current organization of the CPython Git repository, the main branch is always the target for new features. At some point in the release cycle of the next feature release, a new branch release is made which creates a new separate branch for stabilization and later maintenance of the current in-progress feature release (3.n.0) and the main branch is modified to build a new version (which will eventually be released as 3.n+1.0). While the new branch release step could occur at one of several points in the release cycle, current practice is for it to occur at feature code cutoff for the release which is scheduled for the first beta release.

In the descriptions that follow, steps specific to release types are labeled accordingly, for now, new branch and final.

How To Make A Release

Here are the steps taken to make a Python release. Some steps are more fuzzy than others because there’s little that can be automated (e.g. writing the NEWS entries). Where a step is usually performed by An Expert, the role of that expert is given. Otherwise, assume the step is done by the Release Manager (RM), the designated person performing the release. The roles and their current experts are:

Note

It is highly recommended that the RM contact the Experts the day before the release. Because the world is round and everyone lives in different timezones, the RM must ensure that the release tag is created in enough time for the Experts to cut binary releases.

You should not make the release public (by updating the website and sending announcements) before all experts have updated their bits. In rare cases where the expert for Windows or Mac is MIA, you may add a message “(Platform) binaries will be provided shortly” and proceed.

We use the following conventions in the examples below. Where a release number is given, it is of the form 3.X.YaN, e.g. 3.13.0a3 for Python 3.13.0 alpha 3, where “a” == alpha, “b” == beta, “rc” == release candidate.

Release tags are named v3.X.YaN. The branch name for minor release maintenance branches is 3.X.

As much as possible, the release is automated and guided by the run_release.py script, which is available in a separate repository: python/release-tools. This helps by automating many of the following steps, and guides you to perform some manual steps.

  • Log into Discord and join the Python Core Devs server. Ask another RM for an invite.

    You probably need to coordinate with other people around the world. This communication channel is where we’ve arranged to meet.

  • Check to see if there are any showstopper bugs.

    Go to https://github.com/python/cpython/issues and look for any open bugs that can block this release. You’re looking at two relevant labels:

    release-blocker
    Stops the release dead in its tracks. You may not make any release with any open release blocker bugs.
    deferred-blocker
    Doesn’t block this release, but it will block a future release. You may not make a final or candidate release with any open deferred blocker bugs.

    Review the release blockers and either resolve them, bump them down to deferred, or stop the release and ask for community assistance. If you’re making a final or candidate release, do the same with any open deferred.

  • Check the stable buildbots.

    Go to https://buildbot.python.org/all/#/release_status

    Look at the buildbots for the release you’re making. Ignore any that are offline (or inform the community so they can be restarted). If what remains are (mostly) green buildbots, you’re good to go. If you have non-offline red buildbots, you may want to hold up the release until they are fixed. Review the problems and use your judgement, taking into account whether you are making an alpha, beta, or final release.

  • Make a release clone.

    On a fork of the CPython repository on GitHub, create a release branch within it (called the “release clone” from now on). You can use the same GitHub fork you use for CPython development. Using the standard setup recommended in the Python Developer’s Guide, your fork would be referred to as origin and the standard CPython repo as upstream. You will use the branch on your fork to do the release engineering work, including tagging the release, and you will use it to share with the other experts for making the binaries.

    For a final or release candidate 2+ release, if you are going to cherry-pick a subset of changes for the next rc or final from all those merged since the last rc, you should create a release engineering branch starting from the most recent release candidate tag, i.e. v3.8.0rc1. You will then cherry-pick changes from the standard release branch as necessary into the release engineering branch and then proceed as usual. If you are going to take all of the changes since the previous rc, you can proceed as normal.

  • Make sure the current branch of your release clone is the branch you want to release from (git status).
  • Run blurb release <version> specifying the version number (e.g. blurb release 3.4.7rc1). This merges all the recent news blurbs into a single file marked with this release’s version number.
  • Regenerate Lib/pydoc-topics.py.

    While still in the Doc directory, run:

    make pydoc-topics
cp build/pydoc-topics/topics.py ../Lib/pydoc_data/topics.py
  • Commit your changes to pydoc_topics.py (and any fixes you made in the docs).
  • Consider running autoconf using the currently accepted standard version in case configure or other Autoconf-generated files were last committed with a newer or older version and may contain spurious or harmful differences. Currently, Autoconf 2.71 is our de facto standard. if there are differences, commit them.
  • Make sure the SOURCE_URI in Doc/tools/extensions/pyspecific.py points to the right branch in the Git repository (main or 3.X). For a new branch release, change the branch in the file from main to the new release branch you are about to create (3.X).
  • Bump version numbers via the release script:
    .../release-tools/release.py --bump 3.X.YaN

    Reminder: X, Y, and N should be integers. a should be one of a, b, or rc (e.g. 3.4.3rc1). For final releases omit the aN (3.4.3). For the first release of a new version Y should be 0 (3.6.0).

    This automates updating various release numbers, but you will have to modify a few files manually. If your $EDITOR environment variable is set up correctly, release.py will pop up editor windows with the files you need to edit.

    Review the blurb-generated Misc/NEWS file and edit as necessary.

  • Make sure all changes have been committed. (release.py --bump doesn’t check in its changes for you.)
  • For a final major release, edit the first paragraph of Doc/whatsnew/3.X.rst to include the actual release date; e.g. “Python 2.5 was released on August 1, 2003.” There’s no need to edit this for alpha or beta releases.
  • Do a git status in this directory.

    You should not see any files, i.e., you better not have any uncommitted changes in your working directory.

  • Tag the release for 3.X.YaN:
    .../release-tools/release.py --tag 3.X.YaN

    This executes a git tag command with the -s option so that the release tag in the repo is signed with your GPG key. When prompted choose the private key you use for signing release tarballs etc.

  • For