Development Workflow

Learn the standard workflow for contributing to CPython

This guide covers the typical workflow for contributing code to CPython, from creating a branch to submitting a pull request.

Overview

The CPython development workflow follows standard GitHub practices:

1. Create an issue (for non-trivial changes)
2. Create a feature branch
3. Make your changes
4. Test your changes
5. Commit your changes
6. Push and create a pull request
7. Address review feedback
8. Merge when approved

Before You Start

Ensure you have:

• Set up your development environment
• Built CPython successfully
• Familiarized yourself with the Developer Guide

Creating an Issue

For most changes, create an issue first:

1. Check for existing issues

   Search github.com/python/cpython/issues to avoid duplicates.

2. Create a new issue

   If none exists, create a new issue describing:

   • The problem or feature request
   • Expected behavior
   • Current behavior (for bugs)
   • Python version
   • Platform information
3. Discuss the approach

   For significant changes, discuss the implementation approach before writing code.

Trivial changes like fixing typos don’t require an issue.

Creating a Branch

Create a feature branch for your work:

# Update your main branch
git checkout main
git pull upstream main

# Create and checkout a new branch
git checkout -b gh-NNNNN-fix-description

Branch naming convention:

• Use gh-NNNNN prefix (where NNNNN is the issue number)
• Add a descriptive name
• Use hyphens, not underscores

Examples:

• gh-12345-fix-dict-memory-leak
• gh-67890-add-frozenset-optimization

Making Changes

Edit Code

Make your changes following the code style guide:

# Edit files
vim Lib/os.py
vim Modules/posixmodule.c

Build and Test

After making changes, build and test:

# For development, build without optimizations
make

# Run relevant tests
./python -m test test_os

# Run the full test suite
make test

Add Tests

Always add tests for new features or bug fixes:

# In Lib/test/test_os.py
def test_new_feature(self):
    result = os.new_function()
    self.assertEqual(result, expected_value)

Update Documentation

Update documentation for new features:

# Edit relevant .rst files in Doc/
vim Doc/library/os.rst

# Build documentation
cd Doc
make html

See Contributing to Documentation for details.

Committing Changes

Commit Message Format

Follow the commit message format:

gh-NNNNN: Brief summary (50 chars or less)

More detailed explanation if needed. Wrap at 72 characters.
Explain what changed and why, not how.

- Can use bullet points
- For multiple changes

Co-authored-by: Name <[e-mail]>

Making the Commit

# Stage your changes
git add Lib/os.py Modules/posixmodule.c Lib/test/test_os.py

# Commit with a descriptive message
git commit

Example commit message:

gh-12345: Fix memory leak in dict implementation

The dict resize operation was not properly releasing references
to old entries, causing memory leaks in long-running applications.

This fix ensures all old entries are properly deallocated during
the resize operation.

Commit Guidelines

• Make atomic commits (one logical change per commit)
• Write clear, concise commit messages
• Reference the issue number (gh-NNNNN)
• Explain why, not just what
• Sign your commits if required

Pushing and Creating a Pull Request

1. Push your branch

   git push origin gh-12345-fix-description
   
2. Create pull request

   Visit GitHub and click “Create pull request” or use the GitHub CLI:

   gh pr create --title "gh-12345: Fix memory leak in dict" \
                --body "Fixes #12345"
   
3. Fill out PR template

   Your PR description should include:

   • Summary of changes
   • Link to the issue (“Fixes #12345”)
   • Testing done
   • Any breaking changes

Pull Request Title Format

gh-NNNNN: Summary of the changes made

For backport PRs to maintenance branches:

[3.13] gh-NNNNN: Summary (GH-MMMMM)

Where:

• [3.13] is the branch name
• gh-NNNNN is the issue number
• GH-MMMMM is the original PR number from main

Code Review Process

Responding to Reviews

1. Read feedback carefully

   Review all comments from maintainers and other contributors.

2. Make requested changes

   # Make changes
   vim Lib/os.py
   
   # Commit changes
   git add Lib/os.py
   git commit -m "Address review feedback"
   
   # Push updates
   git push origin gh-12345-fix-description
   
3. Reply to comments

   Respond to review comments, especially if you disagree or need clarification.

4. Request re-review

   After addressing feedback, request a re-review from the reviewer.

CI/CD Checks

Your PR must pass all CI checks:

• GitHub Actions: Linux, macOS, Windows builds
• Azure Pipelines: Additional platform coverage
• Tests: All test suites must pass
• Documentation: Doc builds must succeed

Check CI results and fix any failures:

# Pull latest changes from upstream
git fetch upstream
git rebase upstream/main

# Fix issues and push
git push origin gh-12345-fix-description --force-with-lease

Keeping Your Branch Updated

Rebasing on Main

Keep your branch up to date with main:

# Fetch latest changes
git fetch upstream

# Rebase your branch
git rebase upstream/main

# If conflicts occur, resolve them
git status
vim conflicted_file.py
git add conflicted_file.py
git rebase --continue

# Force push (use with caution)
git push origin gh-12345-fix-description --force-with-lease

Never use --force without --with-lease. It’s safer and prevents accidentally overwriting others’ work.

After Your PR is Merged

1. Update your local repository

   git checkout main
   git pull upstream main
   
2. Delete your feature branch

   # Delete local branch
   git branch -d gh-12345-fix-description
   
   # Delete remote branch
   git push origin --delete gh-12345-fix-description
   
3. Close related issues

   If not automatically closed, manually close the issue with a comment linking to the merged PR.

Backporting Changes

For bug fixes that need to be backported to maintenance branches:

1. Wait for the PR to be merged to main
2. A core developer will typically handle backports
3. If asked to backport yourself:

# Cherry-pick to maintenance branch
git fetch upstream
git checkout -b backport-3.13 upstream/3.13
git cherry-pick <commit-hash>

# Create backport PR
git push origin backport-3.13
gh pr create --base 3.13 --title "[3.13] gh-12345: Fix (GH-67890)"

Working with Multiple PRs

If you’re working on multiple issues:

# Keep branches separate
git checkout main
git checkout -b gh-11111-feature-a
# work on feature A...

git checkout main
git checkout -b gh-22222-feature-b
# work on feature B...

# Switch between branches
git checkout gh-11111-feature-a

Troubleshooting

Merge conflicts

When rebasing causes conflicts:

# View conflicts
git status

# Edit files to resolve conflicts
vim conflicted_file.py

# Mark as resolved
git add conflicted_file.py

# Continue rebase
git rebase --continue

Failed CI checks

Common CI failures:

• Test failures: Run tests locally and fix
• Linting errors: Follow code style guide
• Doc build failures: Check .rst syntax
• Platform-specific: May need maintainer help

PR is stale

If your PR has been open for a while:

# Rebase on latest main
git fetch upstream
git rebase upstream/main
git push origin branch-name --force-with-lease

# Add a comment asking for review

Need to update PR description

Edit the PR description on GitHub to:

• Update status
• Add more context
• Link related issues

Best Practices

• Small PRs: Keep changes focused and reviewable
• Test thoroughly: Don’t rely only on CI
• Be patient: Reviews can take time
• Be responsive: Address feedback promptly
• Be respectful: Follow the Code of Conduct
• Communicate: Ask questions if unclear

Next Steps

• Review code style guidelines
• Learn about documentation
• Join Python Discourse
• Read the full Developer Guide

Additional Resources

• CPython Developer Guide
• GitHub Flow Guide
• Python Discourse - Core Development
• Python Issue Tracker