Skip to content

RELEASING.md

Latest commit

 

History

History
298 lines (209 loc) · 7.68 KB

RELEASING.md

File metadata and controls

298 lines (209 loc) · 7.68 KB
Raw

🚀 Release Guide

This guide is for maintainers who want to create new releases of Cascade CLI.

📋 Table of Contents

🔄 Release Process

Automated Release Pipeline

Cascade CLI uses GitHub Actions for fully automated cross-platform releases:

  1. Push a tag → Triggers automated build and release
  2. GitHub Actions builds → Cross-platform binaries (Linux, macOS, Windows)
  3. GitHub Release created → With auto-generated release notes
  4. Binaries tested → Installation verification on all platforms

Supported Platforms

Platform Architecture Binary Name
Linux x64 ca-linux-x64.tar.gz
Linux ARM64 ca-linux-arm64.tar.gz
macOS x64 ca-macos-x64.tar.gz
macOS ARM64 ca-macos-arm64.tar.gz
Windows x64 ca-windows-x64.exe.zip
Windows ARM64 ca-windows-arm64.exe.zip

✅ Pre-Release Checklist

Code Quality

  • All tests pass: cargo test
  • Code compiles: cargo build --release
  • Linting clean: cargo clippy
  • Formatting consistent: cargo fmt
  • Documentation updated: README, CHANGELOG, etc.

Version Management

  • Cargo.toml version updated: Bump version number
  • CHANGELOG.md updated: Document features and fixes
  • Breaking changes documented: If any API changes
  • Migration guide created: If needed for breaking changes

Documentation

  • README.md current: Features, installation, examples
  • User manual updated: Commands or options
  • API documentation: cargo doc generates correctly
  • Examples work: All code examples in docs are functional

Testing

# Comprehensive testing
cargo test --all-features
cargo test --no-default-features
cargo build --release

# Manual testing
./target/release/ca --version
./target/release/ca --help
./target/release/ca stack --help

# Test core workflows
./target/release/ca init
./target/release/ca stacks create test-stack
./target/release/ca stacks list

🎯 Creating a Release

Method 1: Git Tag (Recommended)

# 1. Ensure you're on the main branch
git checkout main
git pull origin main

# 2. Create and push the tag
git tag -a v1.2.3 -m "Release v1.2.3"
git push origin v1.2.3

# 3. GitHub Actions will automatically:
#    - Build cross-platform binaries
#    - Run tests on all platforms
#    - Create GitHub release
#    - Upload binaries as assets

Method 2: Manual Trigger

# Use GitHub's web interface:
# 1. Go to Actions tab
# 2. Select "Release" workflow
# 3. Click "Run workflow" 
# 4. Enter tag name (e.g., v1.2.3)
# 5. Click "Run workflow"

Version Numbering

Follow Semantic Versioning:

  • MAJOR (v2.0.0): Breaking changes
  • MINOR (v1.1.0): Features, backward compatible
  • PATCH (v1.0.1): Bug fixes, backward compatible

Examples:

  • v0.1.1 - Bug fixes and CI improvements
  • v0.1.0 - Initial Beta release
  • v1.1.0 - Added new ca stacks merge command
  • v1.0.1 - Fixed critical bug in rebase logic
  • v2.0.0 - Changed CLI interface (breaking)

📦 Post-Release Tasks

Verify Release

# Check GitHub release page
open https://github.com/JAManfredi/cascade-cli/releases

# Test installation from release
curl -L https://github.com/JAManfredi/cascade-cli/releases/latest/download/ca-linux-x64.tar.gz | tar -xz
./ca --version

Update Documentation

  • Update README.md: Change "coming soon" to actual download links

  • Update INSTALLATION.md: Verify installation instructions work

  • Social media: Announce release on relevant platforms

Monitor Release

  • Check GitHub Actions: Ensure all workflows completed successfully
  • Verify binaries: Download and test each platform binary
  • Monitor issues: Watch for installation or functionality issues
  • Check metrics: Monitor download statistics

🔧 Troubleshooting

Common Issues

Build Failures:

# Check specific target
cargo build --release --target x86_64-unknown-linux-gnu

# Cross-compilation issues
rustup target add aarch64-unknown-linux-gnu

Test Failures:

# Run tests with verbose output
cargo test -- --nocapture

# Test specific module
cargo test stack::tests

Release Workflow Failures:

# Check GitHub Actions logs
# Common issues:
# - Cargo.toml version not updated
# - Missing dependencies for cross-compilation
# - Test failures on specific platforms

Manual Release Recovery

If automated release fails, you can create a manual release:

# 1. Build all targets locally
cargo build --release --target x86_64-unknown-linux-gnu
cargo build --release --target x86_64-apple-darwin
cargo build --release --target x86_64-pc-windows-msvc

# 2. Create packages
cd target/x86_64-unknown-linux-gnu/release
tar czf ca-linux-x64.tar.gz cc

# 3. Upload to GitHub Release manually

Rollback Process

If a release has critical issues:

# 1. Delete the GitHub release
gh release delete v1.2.3

# 2. Delete the tag
git tag -d v1.2.3
git push origin :refs/tags/v1.2.3

# 3. Fix issues and create new release

🛠️ Release Workflow Details

GitHub Actions Workflow

The release workflow (.github/workflows/release.yml) includes:

  1. Multi-platform builds - Linux, macOS, Windows (x64 + ARM64)
  2. Cross-compilation - Uses proper toolchains for each target
  3. Testing - Runs full test suite on native platforms
  4. Packaging - Creates compressed archives for each platform
  5. Release creation - Auto-generates release notes and uploads binaries
  6. Installation testing - Downloads and tests each binary

Release Notes Generation

The workflow automatically generates release notes with:

  • Changelog - Commits since last release
  • Installation instructions - Platform-specific download commands
  • Documentation links - User manual, onboarding guide
  • Feature highlights - Key capabilities and improvements

Binary Naming Convention

  • Format: cc-{platform}-{arch}.{extension}
  • Examples:
    • ca-linux-x64.tar.gz
    • ca-macos-arm64.tar.gz
    • ca-windows-x64.exe.zip

📈 Release Metrics

Success Indicators

  • ✅ All platform builds complete successfully
  • ✅ All tests pass on all platforms
  • ✅ Binaries are under 50MB compressed
  • ✅ Installation works on all platforms
  • ✅ No critical issues reported within 24 hours

Monitoring

  • GitHub Release downloads - Track adoption
  • Issue reports - Monitor for installation/functionality problems
  • Performance metrics - Binary size, startup time
  • User feedback - Community response and suggestions

🤝 Contributing to Releases

For Maintainers

  • Release authority: Only designated maintainers should create releases
  • Testing responsibility: Thoroughly test before releasing
  • Communication: Announce planned releases in advance
  • Documentation: Keep this guide updated with process changes

For Contributors

  • Pull requests: Ensure PRs are tested and documented
  • Version bumps: Don't bump versions in PRs (maintainers handle this)
  • Breaking changes: Clearly document any breaking changes
  • Testing: Include tests for features

*This release guide is maintained by the Cascade CLI team. Last updated: 6/28/25