Skip to content

release-workflow-guide.md

Latest commit

 

History

History
271 lines (189 loc) · 5.76 KB

release-workflow-guide.md

File metadata and controls

271 lines (189 loc) · 5.76 KB
Raw

Release Workflow Quick Start Guide

This guide shows how to use the automated release management system.

Prerequisites

  1. Install Node.js dependencies (first time only):
npm install
  1. Install pre-commit hooks (first time only):
pre-commit install

Daily Development

Making Commits

Follow Conventional Commits format:

# Interactive prompt (recommended for beginners)
npm run commit

# Or write directly
git commit -m "feat: add new feature"
git commit -m "fix: resolve bug in audio processing"
git commit -m "docs: update API documentation"

Commit Types:

  • feat: - New feature (→ MINOR version bump)
  • fix: - Bug fix (→ PATCH version bump)
  • feat!: or BREAKING CHANGE: - Breaking change (→ MAJOR version bump)
  • docs:, chore:, test:, etc. - No version bump

Pre-commit Validation

The pre-commit hook will automatically:

  • Validate commit message format
  • Run linters and formatters
  • Check for secrets

If validation fails, fix the issues and try again.

Creating a Release

1. Ensure Main is Ready

# Make sure you're on main and up to date
git checkout main
git pull origin main

# Verify all CI checks pass
# Check: https://github.com/PatrickFanella/transcript-create/actions

2. Run standard-version

# Automatic version bump based on commits since last release
npm run release

# Or specify version type explicitly
npm run release:patch   # 0.1.0 → 0.1.1 (bug fixes)
npm run release:minor   # 0.1.0 → 0.2.0 (new features)
npm run release:major   # 0.1.0 → 1.0.0 (breaking changes)

This will:

  • Analyze commits since last release
  • Determine version bump (major/minor/patch)
  • Update version in all files:
    • pyproject.toml
    • package.json
    • frontend/package.json
    • clients/javascript/package.json
    • e2e/package.json
  • Update CHANGELOG.md with categorized changes
  • Create a git commit with changes
  • Create a git tag (but not push it)

3. Review Changes

# Review the changelog
cat CHANGELOG.md

# Check version updates
git diff HEAD~1

# If everything looks good, proceed to next step
# If not, reset and fix:
git reset --hard HEAD~1
git tag -d v0.2.0  # Delete the tag
# Fix issues and try again

4. Push to Trigger Release

# Push the commit and tag
git push --follow-tags

# Or separately
git push origin main
git push origin v0.2.0

5. GitHub Actions Takes Over

Once the tag is pushed, GitHub Actions will automatically:

  1. Create GitHub Release by extracting release notes from CHANGELOG.md and publishing the release at https://github.com/PatrickFanella/transcript-create/releases.
  2. Build & Push Docker Images by building the ROCm-enabled image and publishing these tags: ghcr.io/onnwee/transcript-create:v0.2.0, ghcr.io/onnwee/transcript-create:0.2.0, ghcr.io/onnwee/transcript-create:0.2, ghcr.io/onnwee/transcript-create:0, and ghcr.io/onnwee/transcript-create:latest for stable releases.
  3. Notify with a workflow completion notification.

Monitor progress: https://github.com/PatrickFanella/transcript-create/actions

Pre-release Versions

For alpha, beta, or release candidate versions:

# First release candidate for 1.0.0
npm run release -- --prerelease rc
# Creates v1.0.0-rc.0

# Next release candidate
npm run release -- --prerelease rc
# Creates v1.0.0-rc.1

# Alpha release
npm run release -- --prerelease alpha
# Creates v1.0.0-alpha.0

# Beta release
npm run release -- --prerelease beta
# Creates v1.0.0-beta.0

Pre-releases:

  • Are marked as "pre-release" on GitHub
  • Do NOT update the latest Docker tag
  • Are useful for testing before stable release

Hotfix Process

For urgent fixes to production:

# 1. Branch from the release tag
git checkout -b hotfix/v1.2.1 v1.2.0

# 2. Make the fix
git commit -m "fix: critical security vulnerability"

# 3. Run standard-version for patch
npm run release:patch

# 4. Merge to main
git checkout main
git merge hotfix/v1.2.1

# 5. Push with tag
git push --follow-tags

Troubleshooting

Commit message rejected

✖   subject may not be empty [subject-empty]
✖   type may not be empty [type-empty]

Solution: Use the correct format:

git commit -m "feat: your feature description"

Or use interactive mode:

npm run commit

standard-version fails

Error: Could not get the commits

Solution: Ensure you have at least one previous tag, or use --first-release:

npm run release -- --first-release

Want to undo a release

# Delete the local tag
git tag -d v0.2.0

# Reset the commit
git reset --hard HEAD~1

# If already pushed
git push origin :refs/tags/v0.2.0  # Delete remote tag
git push origin main --force  # Reset remote branch (⚠️ careful!)

Docker image not building

Check the workflow status:

https://github.com/PatrickFanella/transcript-create/actions/workflows/release.yml

Common issues:

  • Dockerfile syntax errors
  • Missing dependencies
  • Build timeout

Version Endpoint

Check the deployed version:

# Local
curl http://localhost:8000/version

# Production
curl https://api.yourapp.com/version

Returns:

{
  "version": "0.2.0",
  "git_commit": "abc123def456",
  "build_date": "2025-10-29T19:00:00Z"
}

Resources

Questions?