Development workflow

CPython uses a fairly conventional GitHub flow. The specifics that differ from a typical project are: a mandatory news entry, the make patchcheck gate, and the regeneration of checked-in generated files.

1. Pick or open an issue

Every PR is associated with an issue (or PEP) tracked at https://github.com/python/cpython/issues. Tiny doc fixes can skip this. PRs whose title starts with gh-NNNNN: ... are linked back to issue NNNNN automatically.

2. Branch from main

git switch -c gh-149123-faster-zlib main

The convention for backports (pre-merge) is to do the work on main first and then have the miss-islington bot create the backport PRs against 3.14, 3.13, etc. when the main PR merges. Backports use branches named <branch>-backport-....

3. Make the change

If you touch any of the inputs below you must regenerate before pushing:

Input file	Regenerated by
Grammar/python.gram	make regen-pegen (writes Parser/parser.c)
Python/bytecodes.c	make regen-cases (writes Python/generated_cases.c.h, Python/executor_cases.c.h, Python/optimizer_cases.c.h, plus Include/internal/pycore_uop_*.h and friends)
Parser/Python.asdl	make regen-ast
[clinic input] blocks in any C file	make clinic
Token names (Grammar/Tokens)	make regen-token
Anything above + Unicode tables, opcode IDs, frozen modules	make regen-all (the safe nuclear option)

The full list of regen-* targets is in Makefile.pre.in. Generated files are checked in; that lets you build CPython from a fresh tree without already having Python.

4. Add a news entry

./python -m blurb add        # if you have an in-tree CPython
# or
pipx run blurb add

blurb opens $EDITOR on a template, then writes a file like:

Misc/NEWS.d/next/Library/2026-04-30-12-34-56.gh-issue-149123.AbCdEf.rst

The first paragraph becomes the changelog line. The category in the path (Library, Core_and_Builtins, Tests, Documentation, Build, Windows, macOS, IDLE, Tools-Demos, C_API, Security) determines where it appears in the release notes.

5. Run make patchcheck

make patchcheck

This runs:

• A check that all changed .c/.h files have a corresponding Misc/NEWS.d/next/ entry (unless they're test-only).
• Whitespace checks.
• A check that no merge conflict markers were left.
• A reminder if generators look out of date.

It's intentionally fast — run it before every push.

6. Run the affected tests

./python -m test test_zlib            # one module
./python -m test -j8                  # full suite (parallel)
./python -m test -uall                # all resource categories
./python -m test -W test_zlib         # re-run failures verbosely

See Testing for buckets of tests, slow tests, and how to write new ones.

7. Push and open the PR

The PR template asks for the issue number, the news entry, and a description. CI is mandatory on:

• Linux x86_64 (default and --with-pydebug)
• Windows
• macOS
• WASI
• Free-threaded build (--disable-gil)
• JIT build (--enable-experimental-jit)
• Documentation build
• Lint (mypy, ruff, clinic --check, regen status, link check)

CI workflows are under .github/workflows/. Re-pushes restart all required checks.

8. Address review

CODEOWNERS auto-assigns reviewers per .github/CODEOWNERS — that file mirrors the Experts Index in the devguide. Iterate. Squash-on-merge is the project default, so commit history during review is informational only.

9. Backports

When a fix needs to ship in a maintenance release, label the merged PR with needs backport to 3.14, needs backport to 3.13, etc. The miss-islington bot opens the backport PRs and tags the original author. Each backport runs CI separately.

10. Reverts

A revert PR keeps the original commit message prefixed with Revert: and bumps the issue. CPython routinely reverts changes when a regression is found post-merge; this is healthy and not a stigma.

Useful Makefile shortcuts

Command	What it does
make	Build the interpreter.
make -j$(nproc)	Parallel build.
make clean	Remove object files.
make distclean	Reset to "fresh checkout" state.
make test	Run the standard test suite.
make buildbottest	Like make test with all resources enabled (-uall).
make patchcheck	The pre-push lint + news-entry check.
make regen-all	Regenerate every checked-in generated file.
make pythoninfo	Dump build info, useful in bug reports.
make profile-opt	Build with PGO (slow; for releases/benchmarks).
make tags / make TAGS	Build ctags/etags index.

Where the bots live

Bot	What it does
bedevere	Adds the issue link, enforces blurb requirements, manages labels.
miss-islington	Opens backport PRs and merges them after CI.
cpython-cla-bot	Verifies every contributor has signed the PSF CLA.
dependabot	Bumps GitHub Actions and a few documentation deps.

All of them are configured under .github/.