Skip to content

RELEASE.md

Latest commit

 

History

History
194 lines (138 loc) · 5.14 KB

RELEASE.md

File metadata and controls

194 lines (138 loc) · 5.14 KB

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:

Method 1: Automatic Version Detection (Recommended)

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.