barycenter/book/src/development/release-process.md

Release Process

Barycenter uses tag-triggered releases. Pushing a Git tag matching the v*.*.* pattern triggers the CI pipeline to build artifacts, publish container images, and create a GitHub release.

Triggering a Release

1. Prepare the Release

Ensure all changes for the release are merged into main. Update version numbers in Cargo.toml and finalize the changelog.

git checkout main
git pull origin main

2. Create and Push the Tag

git tag v1.2.0
git push origin v1.2.0

The tag name must match the v*.*.* pattern (e.g., v1.0.0, v1.2.3, v2.0.0-rc.1). The CI pipeline triggers automatically on tag push.

3. Monitor the Pipeline

The release pipeline performs several steps in sequence. Monitor it through the GitHub Actions UI or the CLI:

gh run list --workflow=release
gh run watch

Release Pipeline Steps

Step 1: Build Multi-Platform Docker Images

The pipeline builds Docker images for two architectures:

Platform	Architecture	Use Case
linux/amd64	x86_64	Standard servers, cloud instances
linux/arm64	AArch64	ARM servers, AWS Graviton, Apple Silicon

Both images are built from the same Dockerfile using Docker's --platform build argument. Platform-specific build caches are used to optimize parallel builds and avoid cache conflicts between architectures.

The images are tagged with:

• The version tag (e.g., v1.2.0)
• latest (for the most recent stable release)

Step 2: Publish to GitHub Container Registry

Built images are published to GitHub Container Registry (GHCR):

ghcr.io/your-org/barycenter:v1.2.0
ghcr.io/your-org/barycenter:latest

A multi-architecture manifest is created so that docker pull ghcr.io/your-org/barycenter:v1.2.0 automatically selects the correct image for the host platform.

Step 3: Create GitHub Release

The pipeline creates a GitHub release with:

• Release title: The tag name (e.g., v1.2.0)
• Changelog: Auto-generated from commits since the previous release tag, organized by conventional commit type
• Binary artifacts: The compiled barycenter binary for each platform (if configured)

The changelog groups commits by type:

## What's Changed

### Features
- feat: add refresh token rotation (#42)
- feat: add device code flow support (#45)

### Bug Fixes
- fix: prevent double consumption of authorization codes (#43)

### Other Changes
- chore: update sea-orm to 1.1.0 (#44)
- docs: add PKCE security documentation (#46)

Step 4: Generate Artifact Attestation

The pipeline generates artifact attestation for the published container images. Attestation provides a cryptographic proof that the container image was built by the CI pipeline from a specific commit in the repository.

This allows consumers to verify the provenance of the image:

gh attestation verify oci://ghcr.io/your-org/barycenter:v1.2.0 \
  --owner your-org

Version Numbering

Barycenter follows Semantic Versioning:

Component	When to Increment	Example
Major (X.0.0)	Breaking changes to the public API, configuration format, or database schema that requires manual migration	v1.0.0 to v2.0.0
Minor (0.X.0)	New features, non-breaking additions to the API or configuration	v1.0.0 to v1.1.0
Patch (0.0.X)	Bug fixes, security patches, documentation updates	v1.0.0 to v1.0.1

Pre-release versions use a suffix: v1.2.0-rc.1, v1.2.0-beta.1.

Hotfix Releases

For urgent production fixes:

1. Create a hotfix branch from the latest release tag:

   git checkout -b hotfix/1.2.1 v1.2.0
   

2. Apply the fix and commit with conventional commit format.

3. Merge into main and tag:

   git checkout main
   git merge hotfix/1.2.1
   git tag v1.2.1
   git push origin main --tags
   

4. Merge back into develop:

   git checkout develop
   git merge hotfix/1.2.1
   git push origin develop
   

The tag push triggers the same release pipeline.

Post-Release Checklist

After a release is published:

• Verify the GitHub release page has the correct changelog and artifacts
• Verify the Docker image is pullable from GHCR: docker pull ghcr.io/your-org/barycenter:vX.Y.Z
• Verify the multi-arch manifest works on both amd64 and arm64
• Verify artifact attestation: gh attestation verify oci://ghcr.io/your-org/barycenter:vX.Y.Z --owner your-org
• Update deployment configurations to reference the new version
• Announce the release to stakeholders if it contains user-facing changes
• Merge the release branch (or main) back into develop if not already done