Skip to content

RELEASE.md

Latest commit

 

History

History
292 lines (207 loc) · 6.71 KB

RELEASE.md

File metadata and controls

292 lines (207 loc) · 6.71 KB

PyPI Release Guide

This guide covers how to release new versions of iriusrisk-cli to PyPI.

Prerequisites

1. Install Build Tools

pip install --upgrade build twine

2. Create PyPI Accounts

  1. Create account at https://pypi.org/ (production)
  2. Create account at https://test.pypi.org/ (testing)
  3. Enable 2FA on both accounts (required for uploads)
  4. Create API tokens:

3. Configure Twine (Optional but Recommended)

Create ~/.pypirc to store credentials:

[distutils]
index-servers =
    pypi
    testpypi

[pypi]
username = __token__
password = pypi-...your-token-here...

[testpypi]
repository = https://test.pypi.org/legacy/
username = __token__
password = pypi-...your-testpypi-token-here...

Important: Set proper permissions: chmod 600 ~/.pypirc

Release Process

Step 1: Prepare the Release

  1. Update Version Number

    Update version in both files:

    • setup.py (line 11)
    • src/iriusrisk_cli/__init__.py (line 3)

  2. Update CHANGELOG.md

    Document changes in the new version:

    ## [0.2.0] - YYYY-MM-DD

### Added
- New feature descriptions

### Changed
- Changes to existing functionality

### Fixed
- Bug fixes

### Removed
- Deprecated features removed

  3. Commit Version Changes

    git add setup.py src/iriusrisk_cli/__init__.py CHANGELOG.md
git commit -m "Bump version to 0.2.0"

Step 2: Build the Package

  1. Clean Previous Builds

    rm -rf build/ dist/ src/*.egg-info

  2. Build Distribution Files

    python -m build

    This creates:

    • dist/iriusrisk_cli-X.Y.Z.tar.gz (source distribution)
    • dist/iriusrisk_cli-X.Y.Z-py3-none-any.whl (wheel)

  3. Verify Package Integrity

    twine check dist/*

    Should see: PASSED for all files.

Step 3: Test on TestPyPI

  1. Upload to TestPyPI

    twine upload --repository testpypi dist/*

    Or with explicit credentials:

    twine upload --repository testpypi --username __token__ --password YOUR_TESTPYPI_TOKEN dist/*

  2. Test Installation from TestPyPI

    Create a test virtual environment:

    python -m venv test-env
source test-env/bin/activate  # On Windows: test-env\Scripts\activate

# Install from TestPyPI
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ iriusrisk-cli

# Test the installation
iriusrisk --version
iriusrisk --help

# Deactivate and remove test environment
deactivate
rm -rf test-env

    Note: --extra-index-url is needed because dependencies (click, requests, etc.) are only on production PyPI.

Step 4: Release to Production PyPI

Once TestPyPI installation is verified:

  1. Upload to Production PyPI

    twine upload dist/*

    Or with explicit credentials:

    twine upload --username __token__ --password YOUR_PYPI_TOKEN dist/*

  2. Verify on PyPI

    Check the package page: https://pypi.org/project/iriusrisk-cli/

  3. Test Production Installation

    python -m venv test-env
source test-env/bin/activate

pip install iriusrisk-cli
iriusrisk --version
iriusrisk test  # Test connection (requires IriusRisk credentials)

deactivate
rm -rf test-env

Step 5: Tag and Push Release

  1. Create Git Tag

    git tag -a v0.2.0 -m "Release version 0.2.0"
git push origin v0.2.0
git push origin main

  2. Create GitHub Release (if using GitHub)

Post-Release Tasks

  1. Update README (if needed)

    • Add PyPI version badge
    • Update installation instructions
    • Update compatibility notes

  2. Announce Release

    • Post on relevant channels
    • Update documentation sites
    • Notify users of breaking changes

Version Numbering

Follow Semantic Versioning:

  • MAJOR (X.0.0): Incompatible API changes
  • MINOR (0.X.0): New features, backward compatible
  • PATCH (0.0.X): Bug fixes, backward compatible

Examples:

  • Bug fix: 0.1.0 → 0.1.1
  • New feature: 0.1.1 → 0.2.0
  • Breaking change: 0.2.0 → 1.0.0

Troubleshooting

Upload Fails with 403 Error

  • Verify API token is correct
  • Ensure 2FA is enabled on your PyPI account
  • Check token has upload permissions

Package Already Exists

PyPI doesn't allow re-uploading the same version. You must:

  1. Increment version number
  2. Rebuild package
  3. Upload new version

Import Errors After Installation

  • Verify all dependencies are listed in install_requires in setup.py
  • Check package structure with python -m zipfile -l dist/*.whl
  • Test in clean virtual environment

Missing Files in Package

  • Check MANIFEST.in includes necessary files
  • Verify package_data in setup.py is correct
  • Review build warnings for excluded files

Initial Release Checklist

For the first release (0.1.0):

  • Package name iriusrisk-cli is available on PyPI
  • setup.py has complete metadata (URLs, keywords, classifiers)
  • CHANGELOG.md exists with release notes
  • MANIFEST.in explicitly includes all necessary files
  • LICENSE file exists (MIT License)
  • README.md has installation instructions
  • Build and test locally successful
  • Test upload to TestPyPI successful
  • Test installation from TestPyPI successful
  • Upload to production PyPI successful
  • Test installation from production PyPI successful
  • Git tag created and pushed
  • GitHub release created (if applicable)

Quick Reference

# Complete release workflow
rm -rf build/ dist/ src/*.egg-info
python -m build
twine check dist/*
twine upload --repository testpypi dist/*
# Test installation
twine upload dist/*
git tag -a v0.X.Y -m "Release version 0.X.Y"
git push origin v0.X.Y
git push origin main

Package Information

Support

For questions or issues with the release process: