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#
GitHub Repository Setup#
Environment Setup#
1. Create GitHub Environments#
Create the following environments in your repository:
Go to Repository Settings → Environments → New environment
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#
Update version in package files:
# src/__init__.py or similar __version__ = "1.2.3"
Update CHANGELOG.md:
## [1.2.3] - YYYY-MM-DD ### Added - New feature X ### Changed - Modified behavior Y ### Fixed - Bug fix Z
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
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#
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:
Run all checks
Create GitHub release
Await approvals
Deploy to PyPI
Troubleshooting#
Common Issues#
Recovery Steps#
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