Skip to content

release-process.md

Latest commit

 

History

History
247 lines (194 loc) · 7.05 KB

release-process.md

File metadata and controls

247 lines (194 loc) · 7.05 KB
Raw

Release Process for Terraphim AI

This document describes the complete release process for Terraphim AI, including all three main components: server, TUI, and desktop application.

Overview

Terraphim AI uses an automated release process powered by:

  • release-plz: Automated semantic versioning and changelog generation
  • GitHub Actions: Multi-platform builds and artifact generation
  • cargo-deb: Debian package generation
  • Earthly: Consistent Docker image builds
  • Tauri: Cross-platform desktop app packaging

Release Components

Main Binaries

  1. terraphim_server: HTTP API server for backend operations
  2. terraphim-agent: Terminal User Interface with REPL capabilities
  3. terraphim-ai-desktop: Tauri-based desktop application

Package Formats

  • Binary releases: Native binaries for Linux, macOS, and Windows
  • Debian packages: .deb files for Ubuntu/Debian systems
  • Desktop installers: Platform-specific installers (.dmg, .msi, .AppImage)
  • Docker images: Multi-architecture container images
  • Homebrew formula: macOS/Linux package manager integration

Automated Release Workflow

1. Development Phase

  • Developers commit using Conventional Commits
  • release-plz monitors commits and creates/updates release PRs
  • PR includes version bumps and changelog updates

2. Release Preparation

  • Review the release PR created by release-plz
  • Verify version bumps are appropriate
  • Check changelog entries are accurate
  • Test the builds locally if needed

3. Release Execution

  • Merge the release PR to trigger the release
  • release-plz creates git tags (e.g., terraphim_server-v0.1.0)
  • GitHub Actions workflow triggers automatically
  • Multi-platform builds execute in parallel

4. Artifact Generation

The release workflow creates:

Binary Artifacts

terraphim_server-linux-x64
terraphim_server-linux-arm64
terraphim_server-macos-x64
terraphim_server-macos-arm64
terraphim_server-windows.exe

terraphim-agent-linux-x64
terraphim-agent-linux-arm64
terraphim-agent-macos-x64
terraphim-agent-macos-arm64
terraphim-agent-windows.exe

Debian Packages

terraphim-server_0.1.0_amd64.deb
terraphim-server_0.1.0_arm64.deb
terraphim-agent_0.1.0_amd64.deb
terraphim-agent_0.1.0_arm64.deb
terraphim-ai-desktop_0.1.0_amd64.deb
terraphim-ai-desktop_0.1.0_arm64.deb

Desktop Applications

Terraphim-Desktop-0.1.0.dmg          (macOS)
Terraphim-Desktop-0.1.0.AppImage     (Linux)
Terraphim-Desktop-0.1.0.msi          (Windows)

Docker Images

ghcr.io/terraphim/terraphim-server:latest
ghcr.io/terraphim/terraphim-server:v0.1.0

5. Release Publication

  • GitHub release created with all artifacts
  • Docker images pushed to GitHub Container Registry
  • Checksums generated for integrity verification

Configuration Files

Release-plz Configuration (.release-plz.toml)

[workspace]
release_always = false              # Only release via PR merges
dependencies_update = true          # Update dependencies
changelog_update = true             # Generate changelogs
git_release_enable = true           # Create GitHub releases
git_tag_enable = true              # Create git tags
semver_check = true                # Check for breaking changes

# Only release main binaries, not internal crates
[[package]]
name = "terraphim_server"
changelog_path = "./terraphim_server/CHANGELOG.md"

[[package]]
name = "terraphim-ai-desktop"
changelog_path = "./desktop/CHANGELOG.md"

[[package]]
name = "terraphim_tui"
changelog_path = "./crates/terraphim_tui/CHANGELOG.md"

Debian Package Metadata

Each binary includes [package.metadata.deb] configuration for:

  • Package descriptions and dependencies
  • File installation paths
  • License and maintainer information

Manual Release Steps (if needed)

Testing Debian Packages Locally

# Install cargo-deb
cargo install cargo-deb

# Build packages
cargo deb -p terraphim_server
cargo deb -p terraphim-ai-desktop
cargo deb -p terraphim_tui

# Test installation
sudo dpkg -i target/debian/*.deb

Building Multi-Platform Binaries

# Install cross-compilation tool
cargo install cross

# Build for different targets
cross build --release --target x86_64-unknown-linux-musl
cross build --release --target aarch64-unknown-linux-musl
cross build --release --target armv7-unknown-linux-musleabihf

Docker Image Building

# Use Earthly for consistent builds
earthly +docker-all

Version Management

Conventional Commits

  • feat: → Minor version bump
  • fix: → Patch version bump
  • feat!: or BREAKING CHANGE: → Major version bump

Multi-Package Versioning

  • Each component (server, desktop, TUI) has independent versioning
  • Tags follow pattern: <package>-v<version> (e.g., terraphim_server-v0.2.0)
  • Internal crates follow workspace versioning

Installation Methods

End-User Installation

# Homebrew (macOS/Linux)
brew install terraphim/terraphim-ai/terraphim-ai

# Debian/Ubuntu
sudo dpkg -i terraphim-server_*.deb

# Docker
docker run ghcr.io/terraphim/terraphim-server:latest

# Direct binary download
wget https://github.com/terraphim/terraphim-ai/releases/latest/download/terraphim_server-linux-x64
chmod +x terraphim_server-linux-x64
./terraphim_server-linux-x64

Troubleshooting

Common Issues

Release PR Not Created

  • Check conventional commit format
  • Verify .release-plz.toml configuration
  • Ensure changes affect releasable packages

Build Failures

  • Check GitHub Actions workflow logs
  • Verify dependencies are available for target platforms
  • Test builds locally with same environment

Debian Package Issues

  • Ensure cargo-deb metadata is correctly configured
  • Verify file paths exist in assets configuration
  • Check license file paths

Docker Build Issues

  • Ensure Earthly configuration is correct
  • Check for dependency conflicts in multi-arch builds
  • Verify base images support target architectures

Getting Help

  • Check workflow logs in GitHub Actions
  • Review release-plz documentation
  • Test locally with cargo build and cargo deb

Security Considerations

Secrets Management

Required GitHub secrets:

  • GITHUB_TOKEN: Automatically provided by GitHub
  • CARGO_REGISTRY_TOKEN: For publishing to crates.io (if enabled)

Artifact Integrity

  • All releases include checksums.txt with SHA256 hashes
  • Docker images are signed and pushed to ghcr.io
  • Binary releases are created in isolated CI environments

Dependency Security

  • Automated dependency updates via release-plz
  • Semver checks prevent accidental breaking changes
  • Regular security audits via GitHub Dependabot

Monitoring and Metrics

Release Analytics

  • Track download counts from GitHub releases
  • Monitor Docker image pull statistics
  • Review Homebrew installation metrics

Quality Metrics

  • Build success rates across platforms
  • Test coverage maintenance
  • Time from commit to release availability

This automated release process ensures consistent, reliable distribution of Terraphim AI across all supported platforms while maintaining security and quality standards.