mirror of
https://github.com/hanzoai/stack.git
synced 2026-11-19 03:06:57 +00:00
5.1 KiB
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:
Method 1: Automatic Version Detection (Recommended)
Every push to main branch automatically:
- Runs all tests
- Checks each package's version against PyPI
- Publishes any packages with new versions
- 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
- Tests Run First: All tests must pass before any package is published
- Tag-based Triggers: Pushing a tag triggers the release process
- 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 packagehanzo-mcp-*- Releases hanzo-mcp packagehanzo-agents-*- Releases hanzo-agents packagehanzo-memory-*- Releases hanzo-memory packagehanzo-aci-*- Releases hanzo-aci packagehanzo-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:
- Update version in
pyproject.tomlfile(s) - Update CHANGELOG if applicable
- Ensure all tests pass locally
- Commit all changes
- Create and push tag
๐ Security
- PyPI tokens are stored as GitHub secrets
- Use
HANZO_PYPI_TOKENorPYPI_TOKENsecret names - Tokens have package-specific or organization-wide permissions
๐ Release Status
You can monitor release status at:
- GitHub Actions
- PyPI - hanzo
- PyPI - hanzo-network
- PyPI - hanzo-mcp
- PyPI - hanzo-agents
- PyPI - hanzo-memory
- PyPI - hanzo-aci
- PyPI - hanzo-repl
๐ 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.tomlis 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:
- Create package directory in
pkg/ - Add
pyproject.tomlwith proper configuration - Update CI workflows to include the new package
- Add package to this documentation
For questions or issues, please open an issue on GitHub.