Mina Rust Release Process

Work in Progress

This release process documentation is currently being validated and may change. Please coordinate with the release manager before following these procedures for production releases.

This document outlines the complete process for creating and publishing Mina Rust releases.

Release Branch Strategy All releases are made from the main branch.

The release process involves creating a release branch from develop, merging it to main, and then tagging from main.

Prerequisites

• Push access to the main repository
• Docker Hub credentials configured for CI
• GitHub CLI (gh) installed and authenticated
• Write access to create GitHub releases

Release Types

Major Release (v2.0.0)

• Breaking changes to APIs or protocols
• Significant architectural changes
• Requires careful coordination and migration guides

Minor Release (v1.5.0)

• New features and enhancements
• Backward compatible changes
• Performance improvements

Patch Release (v1.4.3)

• Bug fixes and security patches
• Documentation updates
• No new features

Release Communication Checklist

Slack/Communication Template

Copy and paste this checklist when announcing a release in progress:

## 🚀 Release in Progress: vX.Y.Z

**Release Manager:** @[your-name] **Target Date:** [date] **Type:** [ ] Major [
] Minor [ ] Patch

### Pre-Release

- [ ] Develop branch stability verified
- [ ] CHANGELOG.md updated
- [ ] Version compatibility checked
- [ ] Release branch created (if major/minor)
- [ ] Version numbers updated in Cargo.toml files

### Release Process

- [ ] PR created from release branch to main
- [ ] CI tests passing
- [ ] Required approvals obtained
- [ ] PR merged to main
- [ ] Git tag created and pushed
- [ ] Docker images building (automated)
- [ ] GitHub release draft created

### Verification

- [ ] Docker images available on Docker Hub
- [ ] Multi-arch images verified (amd64/arm64)
- [ ] CI pipeline completed successfully
- [ ] GitHub release published

### Post-Release

- [ ] Main branch merged back to develop
- [ ] Documentation updated
- [ ] Release announced in #announcements
- [ ] Known issues documented (if any)

**Tracking:** [Link to PR/Issue] **Status:** 🟡 In Progress

_Updates will be posted in this thread_

Pre-Release Checklist

1. Verify develop branch stability

   # Run complete validation suite (could be skipped as it is supposed to be
   # tested by the CI)
   make release-validate

Script contents (click to expand)

website/docs/developers/scripts/release/validate.sh

#!/bin/bash
set -e

echo "Validating codebase for release..."

echo "Running tests..."
make test

echo "Running tests in release mode..."
make test-release

echo "Checking code formatting..."
make check-format

echo "Fixing trailing whitespace..."
make fix-trailing-whitespace

echo "Verifying no trailing whitespace remains..."
make check-trailing-whitespace

echo "Release validation completed successfully!"

2. Update CHANGELOG.md

   • Move items from [Unreleased] to new version section
   • Follow Keep a Changelog format
   • Include all significant changes since last release

3. Version compatibility check

   • Ensure compatibility with OCaml node if applicable
   • Test against expected network configurations
   • Verify Docker images build successfully

Release Steps

1. Create Release Branch (for major/minor releases)

Release Branch Naming Convention

Release branches must follow the format release/vX.Y.Z where:

• The version must start with a lowercase v
• X, Y, and Z are version numbers following semantic versioning (all three components required)

Valid examples:

• release/v1.5.0
• release/v1.2.3
• release/v2.0.0

Invalid examples:

• release/1.5.0 ❌ (missing 'v' prefix)
• release/v1.5 ❌ (missing patch version)
• release/V1.5.0 ❌ (uppercase 'V')

This naming convention is enforced by CI checks. Any push to a branch starting with release/ that doesn't follow this format will fail validation. :::

# Create release branch from develop
git checkout develop
git pull origin develop
git checkout -b release/v1.5.0
git push -u origin release/v1.5.0

Docker Images for Release Branches After pushing the release branch

CI will automatically build and push Docker images tagged with the branch name. These images are available for local testing while the release PR is being reviewed.

Images will be available as:

• o1labs/mina-rust:v1.5.0
• o1labs/mina-rust-frontend:v1.5.0

To test locally: See Docker Images documentation for complete usage instructions.

# Example usage
docker pull o1labs/mina-rust:v1.5.0
docker run -p 8302:8302 o1labs/mina-rust:v1.5.0

2. Update Version Numbers

# Update all Cargo.toml version fields
make release-update-version VERSION=1.5.0

Script contents (click to expand)

website/docs/developers/scripts/release/update-version.sh

#!/bin/bash
set -e

if [ -z "$1" ]; then
    echo "Error: VERSION is required. Usage: $0 <version>"
    echo "Example: $0 1.2.3"
    exit 1
fi

VERSION="$1"

echo "Updating version to $VERSION in Cargo.toml files..."

# Find all Cargo.toml files, exclude target directory, and update version
find . -name "Cargo.toml" -not -path "./target/*" -exec sed -i.bak 's/^version = "[^"]*"/version = "'"$VERSION"'"/' {} \;

# Clean up backup files
find . -name "*.bak" -delete

echo "Version updated to $VERSION in all Cargo.toml files"

This automatically updates version references in:

• All Cargo.toml files in the workspace
• Excludes target directory files

You may also need to manually update:

• Documentation examples
• Any hardcoded version references in other files

3. Create Release PR

# Create PR from release branch to main
gh pr create --base main --title "Release v1.5.0" --body "$(cat <<'EOF'
## Release v1.5.0

### Summary
Brief description of the release highlights.

### Changes
- Reference the CHANGELOG.md entries
- Highlight breaking changes if any
- Note any special upgrade instructions

### Checklist
- [ ] CHANGELOG.md updated
- [ ] Version numbers updated
- [ ] Tests passing
- [ ] Documentation updated
EOF
)"

4. Review and Merge

• Wait for CI to pass
• Get required approvals
• Merge the release PR to main

5. Create and Push Git Tag

# After merge, switch to main and pull
git checkout main
git pull origin main

# Create and push annotated tag
make release-create-tag TAG=v1.5.0 MESSAGE="Release v1.5.0

## Highlights
- Feature 1: Description
- Feature 2: Description
- Bug fix: Description

See CHANGELOG.md for complete details."

Script contents (click to expand)

website/docs/developers/scripts/release/create-tag.sh

#!/bin/bash
set -e

if [ -z "$1" ] || [ -z "$2" ]; then
    echo "Error: TAG and MESSAGE are required."
    echo "Usage: $0 <tag> <message>"
    echo "Example: $0 v1.2.3 'Release v1.2.3'"
    exit 1
fi

TAG="$1"
MESSAGE="$2"

echo "Creating annotated tag $TAG..."
git tag -a "$TAG" -m "$MESSAGE"

echo "Pushing tag $TAG..."
git push origin "$TAG"

echo "Tag $TAG created and pushed successfully!"

This automatically:

• Creates an annotated tag with the provided message
• Pushes the tag to origin (which triggers Docker image builds)

6. Create GitHub Release

# Create GitHub release from tag
gh release create v1.5.0 \
  --title "Mina Rust v1.5.0" \
  --notes-file RELEASE_NOTES.md \
  --draft

# Or create with auto-generated notes
gh release create v1.5.0 \
  --title "Mina Rust v1.5.0" \
  --generate-notes \
  --draft

7. Verify Automated Processes

After pushing the tag, verify:

1. Docker images are built and pushed

   # Verify multi-arch images are available
   make release-docker-verify TAG=v1.5.0

Script contents (click to expand)

website/docs/developers/scripts/release/verify-docker.sh

#!/bin/bash
set -e

if [ -z "$1" ]; then
    echo "Error: TAG is required. Usage: $0 <tag>"
    echo "Example: $0 v1.2.3"
    exit 1
fi

TAG="$1"
DOCKER_ORG="${DOCKER_ORG:-o1labs}"

echo "Verifying multi-arch Docker images for tag: $TAG"

echo "Checking mina-rust image..."
docker manifest inspect "$DOCKER_ORG/mina-rust:$TAG"

echo "Checking mina-rust-frontend image..."
docker manifest inspect "$DOCKER_ORG/mina-rust-frontend:$TAG"

echo "Multi-arch Docker images verified successfully!"

2. CI pipeline completes successfully

   • Check GitHub Actions status
   • Verify all build matrices pass

3. Docker Hub shows new tags

   • Visit Docker Hub - mina-rust
   • Visit Docker Hub - mina-rust-frontend

8. Publish GitHub Release

Once verification is complete:

# Remove draft status
gh release edit v1.5.0 --draft=false

9. Update Documentation

• Update any documentation that references version numbers
• Announce release in relevant channels
• Update getting started guides if needed

Post-Release Tasks

Merge Back to Develop

# Merge main back to develop to sync version updates
make release-merge-back

Script contents (click to expand)

website/docs/developers/scripts/release/merge-back.sh

#!/bin/bash
set -e

echo "WARNING: This will merge main into develop and push directly."
echo "This operation modifies the develop branch and cannot be easily undone."
echo ""

read -r -p "Are you sure you want to proceed? (y/N): " confirm
if [ "$confirm" != "y" ] && [ "$confirm" != "Y" ]; then
    echo "Operation cancelled."
    exit 1
fi

echo "Merging main back to develop..."
git checkout develop
git pull origin develop
git merge main --no-edit
git push origin develop

echo "Successfully merged main back to develop"

This target includes safety confirmations since it pushes directly to develop.

Tag Docker Images as Latest (for major releases)

For major releases, you may want to tag as latest:

# This would typically be done via additional CI job or manually
docker pull o1labs/mina-rust:v2.0.0
docker tag o1labs/mina-rust:v2.0.0 o1labs/mina-rust:latest
docker push o1labs/mina-rust:latest

Hotfix Process

For urgent patches to released versions:

1. Create hotfix branch from the release tag

   git checkout v1.5.0
   git checkout -b hotfix/v1.5.1

2. Apply minimal fix

   • Make only essential changes
   • Update CHANGELOG.md with patch entry

3. Follow standard release process

   • Create PR to main
   • Create new patch tag (v1.5.1)
   • Verify Docker builds
   • Create GitHub release

Addressing Release problems

If issues are discovered after release:

1. Immediate mitigation

   • Remove problematic Docker tags if possible
   • Update release notes with known issues

2. Create hotfix release

   • Follow hotfix process above
   • Clearly document the fix in release notes

Release Automation

The project uses GitHub Actions for automated building and publishing:

• Trigger: Git tag push
• Process: Native multi-arch builds, Docker Hub push
• Artifacts: Docker images for linux/amd64 and linux/arm64

See .github/workflows/docker.yaml for implementation details.

Makefile Release Targets

The project includes dedicated Makefile targets to streamline the release process:

# Show all release management commands
make release-help

# Common workflow
make release-validate                                    # Validate codebase
make release-update-version VERSION=1.2.3              # Update versions
# Create PR, get approval, merge to main
make release-create-tag TAG=v1.2.3 MESSAGE="Release"   # Create and push tag
make release-docker-verify TAG=v1.2.3                  # Verify Docker images
make release-merge-back                                 # Merge back to develop

Available Targets

• release-validate - Run complete validation suite (tests, format, etc.)
• release-update-version - Update version in all Cargo.toml files
• release-create-tag - Create annotated tag and push to origin
• release-docker-verify - Verify multi-arch Docker images are available
• release-merge-back - Merge main back to develop (with confirmation)
• release-help - Show detailed help for all release targets

Troubleshooting

Docker Build Failures

• Check runner availability (ubuntu-latest, ubuntu-24.04-arm)
• Verify Docker Hub credentials in repository secrets
• Check for dependency or build issues in CI logs

Tag Already Exists

# Delete and recreate tag if needed (use with caution)
git tag -d v1.5.0
git push origin :refs/tags/v1.5.0
# Then recreate tag

CI Pipeline Issues

• Check GitHub Actions status page
• Verify repository secrets are correctly configured
• Review workflow file changes that might affect release process