Release Process

Versioning

Versions follow semver in pyproject.toml. Changelog source: docs/CHANGELOG.md (Commitizen).

just bump-dry    # preview
just bump        # patch bump + changelog
just changelog   # regenerate changelog only

Pre-Release Checklist

1. just quality-gates
2. pnpm --dir web run docs:generate && pnpm --dir web run build
3. uv run proxywhirl sources --validate --fail-on-unhealthy --timeout 5 --concurrency 5
4. Review generated changelog and OpenSpec tasks if applicable

GitHub Release

Tagged pushes trigger .github/workflows/release.yml for PyPI publish and GitHub release artifacts.

Production Deploy

1. Build and push container image (CD workflow or manual)
2. Run ./deploy/scripts/blue-green-deploy.sh or Helm upgrade
3. ./deploy/scripts/health-check.sh
4. Monitor Grafana error rate and latency for 15–30 minutes

Rollback

• Blue/green: ./deploy/scripts/blue-green-deploy.sh rollback
• Helm: helm rollback proxywhirl <revision>
• Database: ./deploy/scripts/backup-restore.sh restore <backup>

See CI/CD and Deployment.