Skip to content

RELEASING.md

Latest commit

 

History

History
299 lines (224 loc) · 7.55 KB

RELEASING.md

File metadata and controls

299 lines (224 loc) · 7.55 KB

Release Process Documentation

This document outlines the complete release process for the Dotloop Python API wrapper project.

Overview

The project uses an automated release process that:

  • Follows semantic versioning (MAJOR.MINOR.PATCH)
  • Automatically publishes to PyPI when version tags are pushed
  • Creates GitHub releases with changelog information
  • Runs comprehensive tests and quality checks
  • Supports both regular and pre-release versions

The default GitHub Actions release path uses PyPI Trusted Publishing via GitHub OIDC.

Prerequisites

Before creating a release, ensure:

  1. Development Environment Setup:

    pip install -e ".[dev]"

  2. Git Configuration:

    git config user.name "Your Name"
git config user.email "your.email@example.com"

  3. Clean Working Directory:

    git status  # Should show no uncommitted changes

  4. All Tests Pass:

    pytest --cov=dotloop --cov-fail-under=100

  5. Code Quality Checks:

    black --check dotloop tests
isort --check-only dotloop tests
flake8 dotloop tests
mypy dotloop

Release Types

Patch Release (1.0.0 → 1.0.1)

For bug fixes and minor improvements:

python scripts/bump_version.py patch

Minor Release (1.0.0 → 1.1.0)

For new features that are backward compatible:

python scripts/bump_version.py minor

Major Release (1.0.0 → 2.0.0)

For breaking changes:

python scripts/bump_version.py major

Step-by-Step Release Process

1. Prepare the Release

  1. Update Documentation:

    • Review and update README.md
    • Update API documentation if needed
    • Ensure all examples work with current code

  2. Update Changelog:

    • Add new section for the upcoming version in CHANGELOG.md
    • Document all changes since the last release
    • Follow the Keep a Changelog format

  3. Final Testing:

    # Run full test suite
pytest -v --cov=dotloop --cov-report=html

# Check code quality
black --check dotloop tests
isort --check-only dotloop tests
flake8 dotloop tests
mypy dotloop

# Security scan
bandit -r dotloop
safety check

  4. Commit All Changes:

    git add .
git commit -m "Prepare for release vX.Y.Z"
git push origin main

2. Create the Release

  1. Preview the Version Bump (Optional):

    python scripts/bump_version.py --dry-run patch

  2. Execute the Version Bump:

    python scripts/bump_version.py patch  # or minor/major

    This script will:

    • Update version in pyproject.toml
    • Update version in dotloop/__init__.py
    • Commit the changes
    • Create and push a git tag
    • Push changes to the repository

  3. Monitor the Release:

3. Post-Release Tasks

  1. Verify the Release:

    # Test installation from PyPI
pip install dotloop==X.Y.Z

# Test basic functionality
python -c "import dotloop; print(dotloop.__version__)"

  2. Update Documentation:

    • Update any version-specific documentation
    • Announce the release if needed

  3. Prepare for Next Development:

    • Update CHANGELOG.md with new "Unreleased" section
    • Consider updating development dependencies

Automated Release Workflow

The GitHub Actions workflow (.github/workflows/release.yml) automatically:

On Every Push/PR:

  • Runs tests on multiple Python versions (3.8-3.12)
  • Runs tests on multiple platforms (Ubuntu, Windows, macOS)
  • Performs code quality checks (black, isort, flake8, mypy)
  • Runs security scans (bandit, safety)
  • Generates coverage reports

On Version Tag Push:

  • Builds the package
  • Publishes to PyPI using PyPI Trusted Publishing
  • Creates a GitHub release with changelog
  • Uploads build artifacts

Manual Release (Emergency)

If the automated process fails, you can release manually:

  1. Build the Package:

    python -m build

  2. Check the Package:

    twine check dist/*

  3. Upload to PyPI:

    twine upload dist/* --username __token__ --password $PYPI_API_TOKEN

    Set PYPI_API_TOKEN in your shell first. Do not store live tokens in the repository.

Pre-Release Versions

For alpha, beta, or release candidate versions:

  1. Manual Version Update: Edit pyproject.toml and dotloop/__init__.py:

    version = "1.1.0a1"  # Alpha
version = "1.1.0b1"  # Beta  
version = "1.1.0rc1" # Release Candidate

  2. Create Tag Manually:

    git add pyproject.toml dotloop/__init__.py
git commit -m "Bump version to 1.1.0a1"
git tag v1.1.0a1
git push origin main --tags

Rollback Process

If a release needs to be rolled back:

  1. Remove from PyPI (if possible):

    • Contact PyPI support or use the web interface
    • Note: PyPI doesn't allow re-uploading the same version

  2. Create a Hotfix Release:

    python scripts/bump_version.py patch

  3. Communicate the Issue:

    • Update GitHub release notes
    • Notify users through appropriate channels

Configuration

PyPI Trusted Publishing

The automated release workflow is configured for PyPI Trusted Publishing and expects a PyPI publisher entry for this repository/workflow combination.

Configure it in the dotloop project settings on PyPI with:

  • Owner: theperrygroup
  • Repository: dotloop
  • Workflow file: release.yml

Optional Manual Fallback Token

If you need to publish manually with twine, use a PyPI API token via the PYPI_API_TOKEN environment variable. Do not commit the token or store it in repository documentation.

GitHub Secrets Required

  • GITHUB_TOKEN: Automatically provided by GitHub Actions

Troubleshooting

Common Issues

  1. Version Bump Script Fails:

    • Ensure working directory is clean
    • Check that pyproject.toml and init.py exist
    • Verify git is configured correctly

  2. GitHub Actions Fails:

    • Check the workflow logs
    • Verify the PyPI Trusted Publisher is configured correctly
    • If using a manual fallback, verify the PyPI token is valid

  3. PyPI Upload Fails:

    • Check if the version already exists
    • Verify the Trusted Publisher or API token has correct permissions
    • Ensure the package builds correctly

  4. Tests Fail in CI:

    • Run tests locally first
    • Check for platform-specific issues
    • Verify all dependencies are correctly specified

Getting Help

  • Check GitHub Actions logs for detailed error messages
  • Review PyPI upload logs
  • Consult the Python Packaging Guide
  • Open an issue in the repository for project-specific problems

Security Considerations

  • API tokens are stored securely in GitHub Secrets
  • The release process runs in isolated GitHub Actions runners
  • All dependencies are pinned to specific versions
  • Security scans are run on every release

Best Practices

  1. Always test locally before releasing
  2. Keep changelog up to date
  3. Use semantic versioning consistently
  4. Monitor the release process
  5. Verify the release works as expected
  6. Communicate breaking changes clearly
  7. Maintain backward compatibility when possible

This release process ensures reliable, automated deployments while maintaining high code quality and security standards.