Release Guide¶

Automated Binary Releases with cargo-dist¶

Sawabona uses cargo-dist to automatically build and distribute pre-compiled binaries for all supported platforms on every release.

Creating a Release¶

1. Update Version¶

Update the version in Cargo.toml workspace package section:

[workspace.package]
version = "0.2.0"  # Update this

2. Commit Changes¶

git add Cargo.toml
git commit -m "chore: bump version to 0.2.0"

3. Create and Push Tag¶

git tag v0.2.0
git push origin v0.2.0

4. Automatic Build Process¶

Once the tag is pushed, GitHub Actions will automatically:

Run Tests - Ensure all tests pass before building
Build Binaries - Compile for all target platforms:
Linux x86_64 (GNU)
Linux ARM64 (GNU)
macOS Intel (x86_64)
macOS Apple Silicon (ARM64)
Windows x86_64 (MSVC)
Generate Installers - Create installation scripts:
Shell installer for Linux/macOS
PowerShell installer for Windows
Create GitHub Release - Publish release with:
All compiled binaries
Installation scripts
Checksums for verification
Auto-generated release notes

Supported Platforms¶

Platform	Architecture	Target Triple	Installer
Linux	x86_64	x86_64-unknown-linux-gnu	Shell script
Linux	ARM64	aarch64-unknown-linux-gnu	Shell script
macOS	Intel	x86_64-apple-darwin	Shell script
macOS	Apple Silicon	aarch64-apple-darwin	Shell script
Windows	x86_64	x86_64-pc-windows-msvc	PowerShell script

Installation Methods¶

Users can install the released binaries using:

Shell Installer (Linux/macOS)¶

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/theAIstep/sawabona/releases/latest/download/sawabona-installer.sh | sh

PowerShell Installer (Windows)¶

irm https://github.com/theAIstep/sawabona/releases/latest/download/sawabona-installer.ps1 | iex

Manual Download¶

Download binaries directly from the GitHub Releases page.

Verifying Releases¶

After a release is created, verify:

1. Check GitHub Actions¶

Navigate to the Actions tab
Ensure the release workflow completed successfully
Review logs for any warnings or errors

2. Verify Release Assets¶

Check that the latest release contains: - ✅ Linux x86_64 binary (sawabona-x86_64-unknown-linux-gnu.tar.gz) - ✅ Linux ARM64 binary (sawabona-aarch64-unknown-linux-gnu.tar.gz) - ✅ macOS Intel binary (sawabona-x86_64-apple-darwin.tar.gz) - ✅ macOS ARM64 binary (sawabona-aarch64-apple-darwin.tar.gz) - ✅ Windows binary (sawabona-x86_64-pc-windows-msvc.zip) - ✅ Shell installer (sawabona-installer.sh) - ✅ PowerShell installer (sawabona-installer.ps1) - ✅ Checksums files

3. Test Installation¶

Test installers on each platform:

Linux/macOS:

# Download and run installer
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/theAIstep/sawabona/releases/latest/download/sawabona-installer.sh | sh

# Verify installation
sawabona --version

Windows:

# Download and run installer
irm https://github.com/theAIstep/sawabona/releases/latest/download/sawabona-installer.ps1 | iex

# Verify installation
sawabona --version

4. Verify Checksums¶

# Download binary and checksum
curl -LO https://github.com/theAIstep/sawabona/releases/latest/download/sawabona-x86_64-unknown-linux-gnu.tar.gz
curl -LO https://github.com/theAIstep/sawabona/releases/latest/download/sawabona-x86_64-unknown-linux-gnu.tar.gz.sha256

# Verify checksum
sha256sum -c sawabona-x86_64-unknown-linux-gnu.tar.gz.sha256

Testing Releases (Pre-Production)¶

Before creating a production release, test the workflow:

1. Create Test Tag¶

git tag v0.0.1-test
git push origin v0.0.1-test

2. Monitor Workflow¶

Watch the GitHub Actions workflow execution
Verify all build jobs complete successfully
Check that artifacts are uploaded

3. Download and Test¶

Download binaries from the draft release
Test on each platform
Verify functionality

4. Clean Up¶

# Delete test tag locally and remotely
git tag -d v0.0.1-test
git push origin :refs/tags/v0.0.1-test

# Delete draft release on GitHub

Troubleshooting¶

Build Failures¶

Symptom: Build fails on specific platform Solution: - Check GitHub Actions logs for error details - Ensure dependencies are available on all platforms - Verify cross-compilation configuration

Symptom: Test failures block release Solution: - Review test logs - Fix failing tests - Retry with new tag after fix

Missing Artifacts¶

Symptom: Release is missing binaries for some platforms Solution: - Check that all build jobs completed - Verify GitHub Actions workflow includes all targets - Re-run failed jobs if needed

Installer Issues¶

Symptom: Installer script fails to download/install Solution: - Verify URLs in installer scripts are correct - Check GitHub Release assets are public - Test installer in isolated environment

Release Checklist¶

Before creating a release:

[ ] All tests pass locally (cargo test --workspace)
[ ] Version number updated in Cargo.toml
[ ] CHANGELOG updated with release notes
[ ] Documentation reflects new version
[ ] Breaking changes clearly documented
[ ] Migration guide provided (if needed)
[ ] Tag follows semantic versioning (vX.Y.Z)

After creating a release:

[ ] GitHub Actions workflow completed successfully
[ ] All platform binaries present in release
[ ] Installers work on each platform
[ ] Checksums verified
[ ] Release notes accurate and complete
[ ] Documentation updated on website
[ ] Announce release (blog, social media, etc.)

Rollback Procedure¶

If a release has critical issues:

1. Delete Release¶

# Delete tag locally and remotely
git tag -d v0.2.0
git push origin :refs/tags/v0.2.0

# Delete release on GitHub UI

2. Fix Issues¶

Address the critical bugs
Test thoroughly

3. Create New Release¶

Update version (e.g., v0.2.1)
Follow standard release process

Continuous Deployment¶

For automated releases on main branch:

Configure GitHub Actions to trigger on commits to main
Use semantic-release or release-please for automated versioning
Ensure comprehensive test coverage
Set up staging environment for pre-production testing

Support¶

For questions or issues with releases: - Open an issue on GitHub - Contact the maintainers - Check cargo-dist documentation: https://opensource.axo.dev/cargo-dist/