Release Process
This document describes the automated release process for zzson.
Overview
Releases are automatically triggered when a version tag is pushed to the repository. The tag must follow the format v*.*.*
(e.g., v1.2.0
).
Prerequisites
Before creating a release, ensure:
- Version Updated: Update the version in
Cargo.toml
- Changelog Updated: Add release notes to
CHANGELOG.md
- Tests Pass: Run
./build.sh
and ensure all tests pass - Documentation Updated: Update any relevant documentation
GitHub Secrets Required
The following secrets must be configured in the repository settings:
CRATES_IO_TOKEN
: API token for publishing to crates.ioNPM_TOKEN
: API token for publishing to npm (optional)
Creating a Release
- Update Version:
# Edit Cargo.toml and update the version field version = "1.2.0"
- Update Changelog:
```bash
Add a new section to CHANGELOG.md
[1.2.0] - 2025-01-XX
- Feature: Added new functionality
- Fix: Resolved issue with… ```
- Commit Changes:
git add Cargo.toml CHANGELOG.md git commit -m "chore: bump version to 1.2.0" git push
- Create and Push Tag:
git tag v1.2.0 git push origin v1.2.0
Automated Release Workflow
Once the tag is pushed, the GitHub Actions workflow will:
- Create GitHub Release: Generate release notes from commits
- Build Binaries: Compile for multiple platforms:
- Linux (x86_64, aarch64) with musl for static linking
- macOS (x86_64, aarch64)
- Windows (x86_64, i686)
- Build macOS Package: Create .dmg with .pkg installer
- Build WebAssembly: Package WASM module and bindings
- Publish to crates.io: Automatically publish the Rust crate
- Publish to npm: Publish WASM package (if configured)
- Generate Checksums: Create SHA256 checksums for all artifacts
- Update Documentation: Deploy updated docs to GitHub Pages
Release Assets
Each release includes:
- Binary executables for all supported platforms
- macOS installer (.dmg containing .pkg)
- WebAssembly module (tar.gz archive)
- SHA256 checksums for all files
- Source code archives (zip and tar.gz)
Manual Release Steps
If automatic publishing fails:
Publish to crates.io
cargo login <YOUR_API_TOKEN>
cargo publish
Publish to npm
cd npm-pkg
npm login
npm publish --access public
Rollback Process
If a release needs to be rolled back:
- Delete the release from GitHub
- Yank the version from crates.io:
cargo yank --version 1.2.0
- Unpublish from npm (within 72 hours):
npm unpublish @zzson/zzson@1.2.0
- Delete the git tag:
git push --delete origin v1.2.0
Troubleshooting
Build Failures
- Check the GitHub Actions logs for specific errors
- Ensure all dependencies are properly specified
- Verify cross-compilation targets are correctly configured
Publishing Failures
- Verify API tokens are correctly set in GitHub Secrets
- Check that the version doesn’t already exist on the registry
- Ensure package metadata is complete and valid
macOS Package Issues
- Verify the packaging script has executable permissions
- Check that the build completes successfully locally
- Ensure pkgbuild and productbuild tools are available
Security Considerations
- Never commit API tokens to the repository
- Use GitHub Secrets for all sensitive credentials
- Consider signing binaries for production releases
- Enable 2FA on crates.io and npm accounts