Files

5.1 KiB

Release Process for Hanzo Python SDK

This document describes the automated release process for all Python packages in this repository.

๐Ÿ“ฆ Packages

The following Python packages are managed in this repository:

  • hanzo - Core Hanzo AI SDK
  • hanzo-network - Network utilities for Hanzo AI
  • hanzo-mcp - Model Context Protocol implementation
  • hanzo-agents - Agent framework for Hanzo AI
  • hanzo-memory - Memory management for AI agents
  • hanzo-aci - AI Chain Infrastructure
  • hanzo-repl - REPL for Hanzo AI

๐Ÿš€ Automated Release Process

CI/CD Pipeline

The release process is fully automated through GitHub Actions with two methods:

Every push to main branch automatically:

  1. Runs all tests
  2. Checks each package's version against PyPI
  3. Publishes any packages with new versions
  4. Skips packages already published

To release this way:

# Update version in pyproject.toml
# Commit and push to main
git add -A
git commit -m "bump: hanzo-mcp to v1.2.3"
git push origin main
# CI automatically publishes if version is new!

Method 2: Tag-based Release

  1. Tests Run First: All tests must pass before any package is published
  2. Tag-based Triggers: Pushing a tag triggers the release process
  3. Automatic PyPI Upload: Packages are automatically built and uploaded to PyPI

Workflow Files

  • .github/workflows/publish-pypi.yml: Main publishing workflow
  • .github/workflows/hanzo-packages-ci.yml: CI with integrated publishing
  • .github/workflows/test.yml: Test suite that must pass

๐Ÿ“ How to Release

Option 1: Automatic (Easiest) ๐ŸŽฏ

Simply update the version and push to main:

# Update version in package's pyproject.toml
vim pkg/hanzo-mcp/pyproject.toml  # Change version = "1.2.3"

# Commit and push
git add -A
git commit -m "Release hanzo-mcp v1.2.3"
git push origin main

# CI will automatically detect and publish the new version!

Option 2: Using Tags

Release All Packages

To release all packages with the same version:

# Update version in all pyproject.toml files
# Then create and push a tag
git tag v1.2.3
git push origin v1.2.3

Release Individual Package

To release a specific package:

# Update version in the specific package's pyproject.toml
# Then create and push a package-specific tag
git tag hanzo-mcp-1.2.3
git push origin hanzo-mcp-1.2.3

Tag Naming Convention

  • v* - Releases all packages (e.g., v1.2.3)
  • hanzo-* - Releases the main hanzo package (e.g., hanzo-1.2.3)
  • hanzo-network-* - Releases hanzo-network package
  • hanzo-mcp-* - Releases hanzo-mcp package
  • hanzo-agents-* - Releases hanzo-agents package
  • hanzo-memory-* - Releases hanzo-memory package
  • hanzo-aci-* - Releases hanzo-aci package
  • hanzo-repl-* - Releases hanzo-repl package

๐Ÿ”ง Manual Release (Emergency)

If automated release fails, you can manually publish:

# Set PyPI token
export PYPI_TOKEN=your_token_here

# Publish all packages
./bin/publish-all-packages.sh

# Or publish specific package
./bin/publish-all-packages.sh hanzo-mcp

โœ… Release Checklist

Before creating a release tag:

  1. Update version in pyproject.toml file(s)
  2. Update CHANGELOG if applicable
  3. Ensure all tests pass locally
  4. Commit all changes
  5. Create and push tag

๐Ÿ”’ Security

  • PyPI tokens are stored as GitHub secrets
  • Use HANZO_PYPI_TOKEN or PYPI_TOKEN secret names
  • Tokens have package-specific or organization-wide permissions

๐Ÿ“Š Release Status

You can monitor release status at:

๐Ÿ› Troubleshooting

Tests Failing

If tests fail, the release will not proceed. Check:

  • Test logs in GitHub Actions
  • Local test execution with pytest

PyPI Upload Fails

Common issues:

  • Version already exists on PyPI
  • Invalid PyPI token
  • Network issues

Solutions:

  • Bump version number
  • Check GitHub secrets configuration
  • Retry the workflow

Package Not Publishing

Ensure:

  • Tag matches the naming convention
  • Package directory exists in pkg/
  • pyproject.toml is properly configured

๐Ÿ“ˆ Version Management

We follow semantic versioning (MAJOR.MINOR.PATCH):

  • MAJOR: Breaking API changes
  • MINOR: New features, backward compatible
  • PATCH: Bug fixes, backward compatible

๐Ÿค Contributing

When adding a new package:

  1. Create package directory in pkg/
  2. Add pyproject.toml with proper configuration
  3. Update CI workflows to include the new package
  4. Add package to this documentation

For questions or issues, please open an issue on GitHub.