Skip to content

PUBLISHING.md

Latest commit

 

History

History
325 lines (229 loc) · 5.94 KB

PUBLISHING.md

File metadata and controls

325 lines (229 loc) · 5.94 KB
Raw

📦 Publishing AgentCoach to PyPI

This guide walks you through publishing the agentcoach package to PyPI.

Prerequisites

  1. Python 3.9+ installed
  2. PyPI account at https://pypi.org
  3. TestPyPI account (recommended) at https://test.pypi.org
  4. API tokens from both PyPI and TestPyPI

Quick Start

# Install build tools
pip install --upgrade build twine

# Build the package
python -m build

# Upload to TestPyPI (test first!)
twine upload --repository testpypi dist/*

# Upload to PyPI (production)
twine upload dist/*

Step-by-Step Guide

1. Pre-flight Checks

Before publishing, ensure:

# ✅ All tests pass
pytest

# ✅ No uncommitted changes
git status

# ✅ Version is bumped (if not first release)
# Edit pyproject.toml version field

# ✅ CHANGELOG is updated
# Add entry to CHANGELOG.md

# ✅ Clean previous builds
rm -rf dist/ build/ *.egg-info

2. Update Version

Edit pyproject.toml:

[project]
name = "agentcoach"
version = "0.1.1"  # Bump this

Follow Semantic Versioning:

  • MAJOR (1.0.0): Breaking changes
  • MINOR (0.1.0): New features, backwards compatible
  • PATCH (0.0.1): Bug fixes

3. Update CHANGELOG

Add entry to CHANGELOG.md:

## [0.1.1] - 2024-12-30

### Added
- New feature X

### Fixed
- Bug Y

### Changed
- Improved Z

4. Build the Package

# Clean previous builds
rm -rf dist/ build/ *.egg-info agentcoach.egg-info/

# Build source distribution and wheel
python -m build

This creates:

  • dist/agentcoach-0.1.0.tar.gz (source distribution)
  • dist/agentcoach-0.1.0-py3-none-any.whl (wheel)

5. Test on TestPyPI (Recommended)

Create API token:

  1. Go to https://test.pypi.org/manage/account/token/
  2. Create token with scope "Entire account"
  3. Save token securely

Upload:

twine upload --repository testpypi dist/*

When prompted:

  • Username: __token__
  • Password: pypi-... (your TestPyPI token)

Test installation:

# Create test environment
python -m venv test_env
source test_env/bin/activate

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

# Test it works
agentcoach --help
python -c "from agentcoach import analyze_trace; print('✅ Import works')"

# Clean up
deactivate
rm -rf test_env

6. Publish to PyPI

Create API token:

  1. Go to https://pypi.org/manage/account/token/
  2. Create token with scope "Entire account" (or project-specific after first upload)
  3. Save token securely

Upload:

twine upload dist/*

When prompted:

  • Username: __token__
  • Password: pypi-... (your PyPI token)

7. Verify Publication

# Install from PyPI
pip install agentcoach

# Verify
agentcoach --version
python -c "import agentcoach; print(agentcoach.__version__)"

Check package page: https://pypi.org/project/agentcoach/

8. Tag Release in Git

git add .
git commit -m "Release v0.1.0"
git tag -a v0.1.0 -m "Release version 0.1.0"
git push origin main --tags

Using .pypirc (Optional)

Create ~/.pypirc to store repository configs:

[distutils]
index-servers =
    pypi
    testpypi

[pypi]
username = __token__
password = pypi-YOUR_PYPI_TOKEN_HERE

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

Then upload with:

twine upload --repository testpypi dist/*  # TestPyPI
twine upload dist/*                         # PyPI

Automated Publishing with GitHub Actions

See .github/workflows/publish.yml for automated publishing on git tags.

To trigger:

git tag v0.1.0
git push origin v0.1.0

Troubleshooting

"File already exists"

You cannot re-upload the same version. Bump the version number.

"Invalid distribution"

# Check package contents
tar -tzf dist/agentcoach-0.1.0.tar.gz

# Verify metadata
twine check dist/*

"Missing dependencies"

Ensure all dependencies are listed in pyproject.toml.

"Import errors after install"

Check package structure:

# Should show agentcoach/ directory
unzip -l dist/agentcoach-0.1.0-py3-none-any.whl

Best Practices

  1. Always test on TestPyPI first
  2. Use API tokens, not passwords
  3. Keep tokens secure (use environment variables or secrets manager)
  4. Version bump before each release
  5. Update CHANGELOG
  6. Tag releases in git
  7. Test installation in clean environment
  8. Check package page on PyPI after upload

Version Management

Manual Version Bump

Edit pyproject.toml:

version = "0.1.1"

Using bump2version (Recommended)

# Install
pip install bump2version

# Create .bumpversion.cfg
cat > .bumpversion.cfg << EOF
[bumpversion]
current_version = 0.1.0
commit = True
tag = True

[bumpversion:file:pyproject.toml]
search = version = "{current_version}"
replace = version = "{new_version}"

[bumpversion:file:agentcoach/__init__.py]
search = __version__ = "{current_version}"
replace = __version__ = "{new_version}"
EOF

# Bump version
bumpversion patch  # 0.1.0 -> 0.1.1
bumpversion minor  # 0.1.1 -> 0.2.0
bumpversion major  # 0.2.0 -> 1.0.0

Security

  • Never commit API tokens to git
  • Use project-scoped tokens after first upload
  • Rotate tokens periodically
  • Use 2FA on PyPI account
  • Store tokens in environment variables or secrets manager

Resources

Quick Reference

# Build
python -m build

# Check
twine check dist/*

# Upload to TestPyPI
twine upload --repository testpypi dist/*

# Upload to PyPI
twine upload dist/*

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

# Install from PyPI
pip install agentcoach