91. Release Process

The CPython release process turns the development branch into a stable Python version. It covers feature planning, branch management, release candidates, build artifacts, documentation publication, security updates, maintenance releases, and end-of-life policy.

A release is not just a Git tag. It is a coordinated handoff from development to users, distributors, package maintainers, platform vendors, and downstream projects.

91.1 Why the Release Process Matters

CPython is the reference implementation used by most Python users. Each release affects:

application developers
library maintainers
Linux distributions
cloud platforms
CI systems
packaging tools
extension authors
operating system vendors

A release must therefore preserve compatibility where promised, document changes clearly, and provide enough time for the ecosystem to adapt.

The release process controls when changes may land, when behavior becomes frozen, and how fixes are selected for maintenance branches.

91.2 Release Lines

A release line is a version series such as:

Python 3.12
Python 3.13
Python 3.14

Each release line has its own branch after it is created.

Example shape:

main
    active development for the next feature release

3.14
    maintenance branch for Python 3.14.x

3.13
    maintenance branch for Python 3.13.x

3.12
    older maintenance or security branch

The main branch accepts new development. Maintenance branches accept selected fixes.

91.3 Version Numbers

CPython uses version numbers shaped like:

major.minor.micro

Example:

3.14.2

Meaning:

Feature releases introduce new syntax, APIs, behavior changes, and implementation work.

Bugfix releases should avoid new features and focus on safe corrections.

91.4 Development Phases

A CPython feature release moves through several phases.

The strictness increases as the release approaches final.

91.5 Alpha Releases

Alpha releases are early preview releases.

They exist to expose new work to users and downstream projects before the feature set is frozen.

During alpha:

new features may still land
APIs may still change
performance work may continue
documentation may be incomplete
tests and build systems continue to stabilize

Alpha releases are not meant for production use. They are useful for early feedback.

91.6 Beta Releases

Beta releases mark the start of feature freeze.

After beta begins:

new features are generally no longer accepted
behavior should stabilize
documentation should be close to final
compatibility issues receive more scrutiny
bug fixes continue

Beta is important for the ecosystem. Library authors and distributors start testing seriously against the upcoming Python version.

A patch that would have been acceptable during alpha may be rejected during beta if it changes public behavior too much.

91.7 Release Candidates

Release candidates are near-final builds.

At this stage, the bar is high. Accepted changes are usually limited to:

release blockers
serious regressions
critical documentation fixes
build failures
platform breakage
security-sensitive fixes

The goal is stability. A release candidate should be close enough to final that users can test it with confidence.

If a serious problem is found, another release candidate may be created.

91.8 Final Release

The final release is the official stable version.

It includes:

source tarballs
platform installers
documentation
changelog
release notes
version metadata
signed artifacts
Git tag

After final release, the release branch enters maintenance.

New features move to main. The release branch receives only selected fixes.

91.9 Maintenance Branches

After a feature release, its branch continues to receive bug fixes.

Example:

3.14.0
3.14.1
3.14.2

Bugfix releases should be conservative.

Usually acceptable:

crash fixes
incorrect behavior fixes
documentation corrections
test fixes
build fixes
platform compatibility fixes
regression fixes

Usually not acceptable:

new syntax
new public APIs
large refactors
behavior changes without strong justification
risky optimizations

Maintenance branches prioritize stability over novelty.

91.10 Security Branches

After normal bugfix maintenance ends, a branch may enter security-only maintenance.

At this point, accepted changes are much narrower:

security vulnerabilities
severe build or release infrastructure fixes
selected documentation updates when necessary

Ordinary bugs are usually no longer fixed upstream on that branch.

Security maintenance exists to protect users while encouraging migration to supported versions.

91.11 End of Life

A release line eventually reaches end of life.

After end of life:

no upstream bugfix releases
no upstream security releases
no official maintenance

Users should migrate before this point.

Downstream distributors may continue patching old versions, but that is separate from upstream CPython maintenance.

91.12 Branching Model

The active development branch is main.

Before a feature release finalizes, a release branch is created.

Conceptual model:

main
  |
  | feature work for next version
  |
  +-- 3.14 branch
        |
        +-- 3.14.0
        +-- 3.14.1
        +-- 3.14.2

After branching, fixes may need to land in multiple places:

main
maintenance branch
older maintenance branch

Backporting handles this.

91.13 Backports

A backport applies a fix from main to an older supported branch.

Example:

bug fixed in main
    → also needed in 3.14
        → backport to 3.14

Not every fix should be backported.

Backport candidates usually include:

regression fixes
crash fixes
data corruption fixes
documentation corrections
test fixes
platform build fixes

Backport risk matters. A patch that is safe on main may be too risky for a maintenance branch.

91.14 Release Blockers

A release blocker is a problem serious enough to delay a release.

Examples:

interpreter crash in common use
major regression from previous release
broken installer
broken build on supported platform
serious documentation error for new behavior
security issue
standard library failure affecting many users

Release blockers receive priority because they affect the release schedule.

91.15 Buildbots and CI

CPython relies on automated testing across many platforms.

The build infrastructure helps detect:

test failures
compiler failures
platform-specific behavior
reference leaks
memory bugs
installer problems
free-threaded build failures

A patch that passes locally may fail on a buildbot due to platform differences.

Common causes:

filesystem semantics
locale differences
endianness
word size
thread timing
Windows APIs
macOS framework builds
optional dependencies

Release quality depends on this broad testing matrix.

91.16 Release Artifacts

A CPython release may include several artifacts.

Different release managers and experts may handle different platforms.

91.17 Documentation During Release

Documentation must match the released behavior.

Before final release, documentation should be checked for:

new features
changed behavior
deprecated features
removed APIs
command-line flags
environment variables
C API changes
What's New entries
version markers

Documentation mistakes can be release bugs because they mislead users and maintainers.

91.18 What's New

Each feature release has a What's New document.

It summarizes:

new features
important behavior changes
new standard library modules
deprecated features
removed features
C API changes
porting notes
performance changes

This document is one of the first places advanced users and maintainers read after a release.

A good What's New entry is specific and user-facing.

91.19 News Entries and Changelog

Individual changes usually produce news entries.

These are collected into release changelogs.

A good news entry describes the visible result:

Fix a crash when compiling a deeply nested conditional expression.

A weak entry describes only the patch activity:

Update compiler code.

Release changelogs are consumed by users, packagers, and downstream maintainers.

91.20 ABI and C API Stability

Release management must consider binary compatibility.

C extension authors care about:

whether source still compiles
whether existing wheels still import
whether stable ABI promises hold
whether limited API behavior changed

A small internal change can break extensions if it affects public headers, exported symbols, struct visibility, or ABI layout.

Maintenance branches are especially conservative about ABI changes.

91.21 Feature Freeze

Feature freeze is a boundary.

After feature freeze, changes should generally be limited to:

bug fixes
documentation updates
test fixes
release-blocking changes
low-risk compatibility fixes

Feature freeze protects the release schedule and gives downstream projects a stable target.

A proposed late change must justify:

why it cannot wait
why it is low risk
how it was tested
what compatibility effect it has

91.22 Deprecation and Removal

Deprecations usually follow a staged process.

Typical pattern:

document deprecation
emit warning
wait across releases
remove feature
document removal

The exact schedule depends on the feature and project policy.

Deprecation work must update:

runtime warnings
documentation
tests
What's New
migration notes

Removal is more sensitive than addition because it breaks existing code.

91.23 Release Managers

Each Python feature release has a release manager.

The release manager coordinates:

schedule
release candidates
final release
branch policy
release blockers
artifact publication
communication with contributors

The release manager makes practical decisions about timing and risk, especially late in the cycle.

91.24 Contributor Responsibilities

A contributor should understand the release phase before proposing a change.

During early development, larger changes are possible.

During beta, avoid new features.

During release candidate phase, avoid anything not necessary for the release.

Before asking for a backport, consider:

Is this a bug fix?
Is it safe?
Does it affect users on the older branch?
Does it change behavior?
Does it need documentation?
Does it risk ABI compatibility?

91.25 Practical Patch Timing

A patch should land early when it affects:

syntax
bytecode
object layout
C API
standard library public behavior
import machinery
threading
free-threading
platform installers

These areas need more time for testing.

Late changes should be small and easy to reason about.

91.26 Common Release Mistakes

91.27 Core Principle

The CPython release process manages risk.

Development creates change. The release process narrows change into a stable version that users can depend on. As the release approaches final, correctness remains necessary, but predictability becomes just as important.