Release Process

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

Prerequisites

• Maintainer access to the repository
• Git installed and configured
• GitHub CLI (optional, but recommended)

Release Steps

1. Prepare the Release

Ensure all changes for the release are merged to main:

git checkout main
git pull origin main

2. Create a Release Tag

Create and push a semantic version tag:

# Format: v<major>.<minor>.<patch>
git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0

3. Automated Release Process

When you push a tag matching v*.*.*, GitHub Actions automatically:

1. ✅ Builds binaries for:
   • Linux AMD64
   • Linux ARM64
   • Darwin (macOS) ARM64
2. ✅ Creates Docker images for:
   • Linux AMD64
   • Linux ARM64
   • Multi-arch manifest
3. ✅ Publishes Docker images to:
   • ghcr.io/openchami/fabrica:vX.Y.Z
   • ghcr.io/openchami/fabrica:latest
4. ✅ Creates GitHub Release with:
   • Binaries for all platforms
   • Checksums
   • Auto-generated changelog

4. Verify the Release

Check the GitHub Actions workflow:

gh run list --workflow=release.yaml
gh run view <run-id>

Or visit: https://github.com/openchami/fabrica/actions

5. Test the Release

Test Binaries

Download and test a binary:

# Linux AMD64
wget https://github.com/openchami/fabrica/releases/download/v1.0.0/fabrica_1.0.0_linux_x86_64.tar.gz
tar xzf fabrica_1.0.0_linux_x86_64.tar.gz
./fabrica version

# macOS ARM64
wget https://github.com/openchami/fabrica/releases/download/v1.0.0/fabrica_1.0.0_darwin_arm64.tar.gz
tar xzf fabrica_1.0.0_darwin_arm64.tar.gz
./fabrica version

Test Docker Images

# Pull and test
docker pull ghcr.io/openchami/fabrica:v1.0.0
docker run --rm ghcr.io/openchami/fabrica:v1.0.0 version

# Test multi-arch (should work on both AMD64 and ARM64)
docker pull ghcr.io/openchami/fabrica:latest
docker run --rm ghcr.io/openchami/fabrica:latest --help

Release Configuration

The release process is configured in:

• .goreleaser.yaml - GoReleaser configuration
  • Binary builds for multiple platforms
  • Docker image builds
  • Archive creation
  • Changelog generation
• .github/workflows/release.yaml - GitHub Actions workflow
  • Triggered on version tags
  • Runs GoReleaser
  • Publishes to GitHub Releases and GHCR
• Dockerfile - Multi-stage Docker build
  • Minimal Alpine-based image
  • Non-root user
  • Includes templates and docs

Supported Platforms

Binaries

Platform	Architecture	Binary
Linux	AMD64	fabrica_*_linux_x86_64.tar.gz
Linux	ARM64	fabrica_*_linux_arm64.tar.gz
macOS	ARM64	fabrica_*_darwin_arm64.tar.gz

Docker Images

Platform	Image
Linux AMD64	ghcr.io/openchami/fabrica:*-amd64
Linux ARM64	ghcr.io/openchami/fabrica:*-arm64
Multi-arch	ghcr.io/openchami/fabrica:*

Version Numbering

Fabrica follows Semantic Versioning:

• Major version (v1.0.0) - Breaking changes
• Minor version (v1.1.0) - New features (backward compatible)
• Patch version (v1.0.1) - Bug fixes

Troubleshooting

Release Failed

If the GitHub Actions workflow fails:

1. Check the workflow logs in GitHub Actions
2. Fix any issues
3. Delete the tag: git tag -d v1.0.0 && git push origin :refs/tags/v1.0.0
4. Fix the code and re-tag

Docker Push Failed

Ensure the GITHUB_TOKEN has package write permissions:

• Repository Settings → Actions → General → Workflow permissions
• Enable “Read and write permissions”

Binary Build Failed

Check the GoReleaser configuration:

# Test locally (creates snapshot, doesn't publish)
goreleaser release --snapshot --clean

Manual Release

To create a release manually without pushing a tag:

# Install GoReleaser
brew install goreleaser/tap/goreleaser

# Create snapshot (doesn't publish)
goreleaser release --snapshot --clean

# Publish release (requires GITHUB_TOKEN)
export GITHUB_TOKEN=your_token
goreleaser release --clean

Post-Release

After a successful release:

1. ✅ Update documentation if needed
2. ✅ Announce the release (Slack, Discord, etc.)
3. ✅ Close related issues/PRs
4. ✅ Update project roadmap

Release Confidence Checklist

Before tagging a release, ensure the following readiness criteria are met:

Pre-Release Validation

• All integration tests pass locally: go test -v -timeout 10m ./test/integration
• CI workflows pass on main branch (lint, regression tests, govulncheck, REUSE)
• CHANGELOG.md is updated with all changes for this release
• Module compatibility checks are working (preflight validation prevents version mismatches)
• Auth-enabled projects generate and compile successfully

Upgrade Path Testing

• Previous version → current version upgrade is tested:
  • Generate project with previous Fabrica version (e.g., v0.3.1)
  • Run fabrica generate with current CLI version (v0.4.0)
  • Verify generated code compiles and basic operations work

Binary Smoke Testing

Before publishing the GitHub release, manually verify release artifacts:

• Download Linux AMD64 binary and verify:

  fabrica --version
  fabrica init test-project
  cd test-project && fabrica add resource Device && fabrica generate
  

• Download macOS ARM64 binary and verify the same steps

• Test server generation and startup:

  cd test-project && go run ./cmd/server serve --port 8080 &
  curl http://localhost:8080/health
  

Docker Image Smoke Testing

• Pull and test release Docker image:

  docker pull ghcr.io/openchami/fabrica:v${VERSION}
  docker run --rm ghcr.io/openchami/fabrica:v${VERSION} --version
  
  # Test project generation in container
  docker run --rm -v $(pwd):/work -w /work ghcr.io/openchami/fabrica:v${VERSION} \
    init test-docker && cd test-docker && \
    /app/fabrica add resource Service && \
    /app/fabrica generate
  

• Verify multi-arch image manifest exists:

  docker manifest inspect ghcr.io/openchami/fabrica:v${VERSION}
  

Generated Project Quality Gates

• Runtime validation: Run generated server and verify:
  • Health endpoint responds
  • CRUD operations work
  • Error handling returns proper HTTP status codes
  • Validation rejects invalid requests with 400

• Concurrent operations: Verify ETag conflict handling with simultaneous PATCH requests

• Feature flags: Generated projects with --auth, --events, --reconcile compile and run

Documentation & Announcement

• Release notes are clear and include:
  • Key new features with examples
  • Breaking changes (if any) with migration guidance
  • Upgrade instructions
  • Known issues or limitations

• Example READMEs are current (no stale CLI commands)

• API documentation (OpenAPI spec) is up-to-date

Resources

• GoReleaser Documentation
• GitHub Actions Documentation
• Semantic Versioning