barycenter/RELEASE.md

Release Process

This document describes how to create a new release of Barycenter.

Prerequisites

1. Install cargo-release:

   cargo install cargo-release
   

2. Ensure you're on the main branch with a clean working tree:

   git checkout main
   git pull origin main
   git status  # Should show clean working tree
   

3. Verify all tests pass:

   cargo nextest run
   cargo clippy -- -D warnings
   cargo fmt -- --check
   

Release Steps

1. Update CHANGELOG.md

Before releasing, update the CHANGELOG.md:

1. Move all changes from [Unreleased] to a new version section
2. Add the release date
3. Ensure all changes are categorized (Added, Changed, Deprecated, Removed, Fixed, Security)

Example:

## [Unreleased]

## [0.2.0] - 2025-12-01

### Added
- New feature X
- New feature Y

### Fixed
- Bug fix Z

2. Run cargo-release

cargo-release will:

• Bump the version in Cargo.toml
• Update the Helm chart versions
• Create a git commit
• Create a git tag
• Push to GitHub

Dry run first (recommended):

# Patch version bump (0.1.0 -> 0.1.1)
cargo release patch --dry-run

# Minor version bump (0.1.0 -> 0.2.0)
cargo release minor --dry-run

# Major version bump (0.1.0 -> 1.0.0)
cargo release major --dry-run

# Specific version
cargo release 1.0.0 --dry-run

Execute the release:

# Patch release
cargo release patch --execute

# Minor release
cargo release minor --execute

# Major release
cargo release major --execute

# Specific version
cargo release 1.0.0 --execute

3. Automated Release Process

Once the tag is pushed, GitHub Actions will automatically:

1. Build Docker images for multiple platforms:

   • linux/amd64
   • linux/arm64

2. Push images to GitHub Container Registry with tags:

   • ghcr.io/[owner]/barycenter:v1.0.0 (full version)
   • ghcr.io/[owner]/barycenter:1.0 (major.minor)
   • ghcr.io/[owner]/barycenter:1 (major)
   • ghcr.io/[owner]/barycenter:main-<sha> (commit SHA)

3. Create a GitHub Release with:

   • Auto-generated changelog
   • Docker pull instructions
   • Links to documentation

4. Generate attestations for supply chain security

4. Verify the Release

After the release workflow completes:

1. Check GitHub Releases:

   • Visit https://github.com/[owner]/barycenter/releases
   • Verify the release notes are correct
   • Check that all assets are present

2. Test the Docker image:

   docker pull ghcr.io/[owner]/barycenter:v1.0.0
   docker run --rm ghcr.io/[owner]/barycenter:v1.0.0 --version
   

3. Test the Helm chart:

   helm install barycenter ./deploy/helm/barycenter \
     --dry-run \
     --namespace barycenter-test
   

Versioning Strategy

We follow Semantic Versioning:

• MAJOR version (1.0.0 → 2.0.0): Incompatible API changes
• MINOR version (1.0.0 → 1.1.0): Backwards-compatible new features
• PATCH version (1.0.0 → 1.0.1): Backwards-compatible bug fixes

Pre-releases

For alpha, beta, or release candidates:

cargo release 1.0.0-alpha.1 --execute
cargo release 1.0.0-beta.1 --execute
cargo release 1.0.0-rc.1 --execute

Pre-release images are automatically marked as "pre-release" in GitHub.

Hotfix Releases

For urgent fixes:

1. Create a hotfix branch from the release tag:

   git checkout -b hotfix/v1.0.1 v1.0.0
   

2. Make the fix and commit:

   git add .
   git commit -m "fix: critical security issue"
   

3. Run cargo-release:

   cargo release patch --execute
   

4. Merge back to main:

   git checkout main
   git merge hotfix/v1.0.1
   git push
   

Rollback

If you need to rollback a release:

1. Delete the tag locally and remotely:

   git tag -d v1.0.0
   git push origin :refs/tags/v1.0.0
   

2. Delete the GitHub Release:

   • Go to Releases page
   • Click Edit on the release
   • Click Delete

3. Delete the container images:

   • Go to Packages page
   • Select the version
   • Delete the package version

4. Revert the version bump commit:

   git revert HEAD
   git push
   

Troubleshooting

cargo-release fails with dirty working tree

Ensure all changes are committed:

git status
git add .
git commit -m "chore: prepare for release"

GitHub Actions workflow fails

Check the workflow logs:

1. Go to Actions tab
2. Click on the failing workflow
3. Review the error messages
4. Fix the issue and re-run the workflow

Docker image build fails

Common issues:

• Platform-specific build errors: Check Dockerfile for platform compatibility
• Cache issues: Clear GitHub Actions cache and retry
• Dependency issues: Ensure Cargo.lock is up to date

Post-Release Tasks

After a successful release:

1. Announce the release:

   • Update project documentation
   • Post to social media/forums
   • Notify users of breaking changes

2. Monitor for issues:

   • Watch GitHub Issues
   • Check container pull metrics
   • Monitor error reports

3. Plan next release:

   • Create milestone for next version
   • Triage issues and features
   • Update roadmap