Release Process Guide#

This document outlines the release process for our Python package, including environment setup, workflow configuration, and step-by-step release instructions.

Prerequisites#

Required Tokens#

Test PyPI Token
  1. Create account on Test PyPI

  2. Generate API token: Account Settings → API tokens

  3. Scope: Upload to project

  4. Save as TEST_PYPI_TOKEN in GitHub Actions secrets

Production PyPI Token
  1. Create account on PyPI

  2. Generate API token: Account Settings → API tokens

  3. Scope: Upload to project

  4. Save as PYPI_TOKEN in GitHub Actions secrets

Codecov Token
  1. Create account on Codecov

  2. Generate repository upload token

  3. Scope: Repository-specific access

  4. Save as CODECOV_TOKEN in GitHub Actions secrets

GitHub Repository Setup#

Branch Protection
main branch:
☑️ Require pull request reviews
☑️ Require status checks to pass
☑️ Require linear history
☑️ Include administrators
Required Status Checks
  • Unit Tests

  • Integration Tests

  • Security Scans

  • Quality Checks

Environment Setup#

1. Create GitHub Environments#

Create the following environments in your repository:

  1. Go to Repository Settings → Environments → New environment

Staging Environment
Name: staging
Protection rules: None (allows automated RC deployments)
QA Environment
Name: qa
Protection rules:
  - Required reviewers: [QA team members]
  - Wait timer: 0 minutes
  - Deployment branches: main
Environment secrets: None
Production Release Environment
Name: production-release
Protection rules:
  - Required reviewers: [Release managers]
  - Wait timer: 30 minutes
  - Deployment branches: main
Environment secrets: None
Production Deploy Environment
Name: production-deploy
Protection rules:
  - Required reviewers: [Senior engineers, DevOps]
  - Wait timer: 0 minutes
  - Deployment branches: main
Environment secrets:
  - PYPI_TOKEN: [Production PyPI token]

2. Configure Repository Secrets#

Go to Repository Settings → Secrets and variables → Actions → New repository secret

TEST_PYPI_TOKEN: [Test PyPI token]
PYPI_TOKEN: [Production PyPI token]

Release Types#

Release Candidate (RC)#

  • Format: vX.Y.Z-rcN

  • Examples: v1.2.3-rc1, v1.2.3-rc2

  • Purpose: Testing and validation

  • Deploys to: Test PyPI

Production Release#

  • Format: vX.Y.Z

  • Examples: v1.2.3, v2.0.0

  • Purpose: Production deployment

  • Deploys to: Production PyPI

Release Process#

1. Prepare Release#

  1. Update version in package files:

    # src/__init__.py or similar
    __version__ = "1.2.3"
    
  2. Update CHANGELOG.md:

    ## [1.2.3] - YYYY-MM-DD
    
    ### Added
    
    - New feature X
    
    ### Changed
    
    - Modified behavior Y
    
    ### Fixed
    
    - Bug fix Z
    
  3. Create release branch:

    git checkout -b release/v1.2.3
    git add .
    git commit -m "chore: prepare release v1.2.3"
    git push origin release/v1.2.3
    
  4. Create and merge PR to main

2. Create Release Candidate#

# Ensure you're on main and up-to-date
git checkout main
git pull origin main

# Create and push RC tag
git tag v1.2.3-rc1
git push origin v1.2.3-rc1

3. RC Validation Process#

Automated Checks
  • Quality checks

  • Security scans

  • Test suite

  • Build verification

RC Deployment
  • Automatic upload to Test PyPI

  • Creates draft GitHub release

QA Validation
  • Install from Test PyPI

  • Run smoke tests

  • Validate functionality

Review Approvals
  • QA team approves in QA environment

  • Release managers approve in production-release environment

4. Production Release#

After successful RC validation:

# Create and push production tag
git tag v1.2.3
git push origin v1.2.3

The workflow will:

  1. Run all checks

  2. Create GitHub release

  3. Await approvals

  4. Deploy to PyPI

Troubleshooting#

Common Issues#

RC Upload Fails
  • Check Test PyPI token permissions

  • Verify version doesn’t exist on Test PyPI

  • Ensure version follows PEP 440

Workflow Failures
# View workflow logs
gh run list
gh run view [run-id]
Environment Approval Issues
  • Verify reviewer permissions

  • Check environment protection rules

  • Ensure reviewers are in correct teams

Recovery Steps#

Failed RC
# Delete failed RC tag
git tag -d v1.2.3-rc1
git push origin :refs/tags/v1.2.3-rc1

# Create new RC
git tag v1.2.3-rc2
git push origin v1.2.3-rc2
Failed Production Release
  • Do not delete production tags

  • Create new patch version if needed

Best Practices#

Version Management#

  • Follow semantic versioning

  • Use RCs for significant changes

  • Include build metadata in package

Release Notes#

  • Use consistent format

  • Include upgrade instructions

  • Document breaking changes

Security#

  • Never share or commit tokens

  • Review dependency updates

  • Monitor security advisories

Communication#

  • Announce release schedule

  • Document known issues

  • Maintain changelog

Quick Reference#

Commands Cheatsheet#

# Create RC
git tag v1.2.3-rc1
git push origin v1.2.3-rc1

# Create Release
git tag v1.2.3
git push origin v1.2.3

# Delete Tag (only for RCs)
git tag -d v1.2.3-rc1
git push origin :refs/tags/v1.2.3-rc1

# View Tags
git tag -l "v*"

# Check Workflow Status
gh workflow list
gh run list

Required Files#

repository/
├── .github/
│   ├── workflows/
│   │   └── release.yaml
│   └── actions/
├── src/
│   └── __init__.py
├── tests/
├── CHANGELOG.md
└── pyproject.toml