# 91. Release Process # 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: ```text 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: ```text Python 3.12 Python 3.13 Python 3.14 ``` Each release line has its own branch after it is created. Example shape: ```text 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: ```text major.minor.micro ``` Example: ```text 3.14.2 ``` Meaning: | Part | Meaning | |---|---| | `3` | Major version | | `14` | Minor feature release | | `2` | Micro bugfix release | 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. | Phase | Meaning | |---|---| | Development | New features and normal fixes accepted | | Alpha | Feature work still allowed, early testing encouraged | | Beta | Feature freeze begins | | Release candidate | Only critical fixes accepted | | Final | Official stable release | | Bugfix maintenance | Bugfix releases continue | | Security maintenance | Security-only fixes | | End of life | No further upstream fixes | 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: ```text 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: ```text 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: ```text 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: ```text 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: ```text 3.14.0 3.14.1 3.14.2 ``` Bugfix releases should be conservative. Usually acceptable: ```text crash fixes incorrect behavior fixes documentation corrections test fixes build fixes platform compatibility fixes regression fixes ``` Usually not acceptable: ```text 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: ```text 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: ```text 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: ```text 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: ```text 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: ```text bug fixed in main → also needed in 3.14 → backport to 3.14 ``` Not every fix should be backported. Backport candidates usually include: ```text 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: ```text 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: ```text 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: ```text 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. | Artifact | Purpose | |---|---| | Source tarball | Portable source release | | Windows installer | Windows user installation | | macOS installer | macOS user installation | | Documentation | Published docs for the version | | Checksums | Integrity verification | | Signatures | Authenticity verification | | Changelog | User-visible change list | | Git tag | Source control marker | 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: ```text 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: ```text 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: ```text Fix a crash when compiling a deeply nested conditional expression. ``` A weak entry describes only the patch activity: ```text 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: ```text 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: ```text 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: ```text 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: ```text 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: ```text 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: ```text 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: ```text 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: ```text 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 | Mistake | Better approach | |---|---| | Landing risky work during beta | Target next feature release | | Backporting broad refactors | Backport minimal fixes only | | Forgetting docs | Update docs before release | | Missing `What's New` | Add user-facing summary | | Ignoring ABI impact | Check headers and extension behavior | | Treating CI green as enough | Consider platform and ecosystem risk | | Rushing release candidate fixes | Keep changes narrowly scoped | ## 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.