Skip to content

RELEASE.md

Latest commit

 

History

History
178 lines (121 loc) · 3.53 KB

RELEASE.md

File metadata and controls

178 lines (121 loc) · 3.53 KB

Release Process

This document describes how to release new versions of iflow-cli-docker using GoReleaser.

Prerequisites

  1. Install GoReleaser:

    go install github.com/goreleaser/goreleaser/v2@latest

  2. Ensure you have proper GitHub permissions:

    • Write access to the repository
    • Ability to create releases

Release Steps

1. Prepare the Release

  1. Update CHANGELOG_SQLITE.md with changes for the new version
  2. Commit all changes: 
    git add .
git commit -m "chore: prepare for release vX.Y.Z"

2. Create and Push a Tag

# Create an annotated tag
git tag -a v1.0.0 -m "Release v1.0.0"

# Push the tag
git push origin v1.0.0

3. Automatic Release

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

  • Build binaries for multiple platforms (Linux, macOS, Windows)
  • Create checksums
  • Generate a changelog
  • Create a GitHub release
  • Upload all artifacts

4. Manual Release (Optional)

If you need to create a release manually:

# Ensure you're on the tagged commit
git checkout v1.0.0

# Create the release
GITHUB_TOKEN=your_token_here goreleaser release --clean

Local Testing

Before creating a real release, you can test locally:

Test the Configuration

make test-release

Create a Snapshot Release

This creates a local build without publishing:

make snapshot

The binaries will be in the dist/ directory.

Version Numbering

We follow Semantic Versioning:

  • MAJOR version (X.0.0): Incompatible API changes
  • MINOR version (0.X.0): New functionality in a backwards compatible manner
  • PATCH version (0.0.X): Backwards compatible bug fixes

Supported Platforms

GoReleaser builds for:

  • Linux: amd64, arm64
  • macOS: amd64 (Intel), arm64 (Apple Silicon)
  • Windows: amd64

Release Assets

Each release includes:

  1. Binaries: Compressed archives for each platform
  2. Checksums: checksums.txt for verification
  3. Changelog: Auto-generated from commit messages
  4. Source Code: GitHub automatically includes source archives

Troubleshooting

Build Fails

  1. Check the GitHub Actions logs
  2. Test locally with make snapshot
  3. Verify .goreleaser.yaml configuration

Wrong Version Number

The version is determined by the Git tag. Ensure you:

  • Use the correct tag format: vX.Y.Z
  • Push the tag to GitHub

Missing Dependencies

If CGO is required (for SQLite):

# On macOS
brew install gcc

# On Ubuntu/Debian
sudo apt-get install build-essential

Post-Release

After a successful release:

  1. Announce the release (if applicable)
  2. Update documentation if needed
  3. Close related issues/PRs

Development Builds

For development, use:

# Build with dev version info
make dev-build

# Or directly with go
go build -ldflags "-X github.com/cc11001100/iflow-cli-docker/cmd.version=dev" .

CI/CD Configuration

The release workflow is defined in .github/workflows/release.yml:

on:
  push:
    tags:
      - 'v*.*.*'

This triggers on any tag starting with v followed by semver format.

Rollback

If a release has issues:

  1. Delete the GitHub release
  2. Delete the tag locally and remotely: 
    git tag -d v1.0.0
git push origin :refs/tags/v1.0.0
  3. Fix the issues
  4. Create a new patch version

Additional Resources