vibetunnel/docs/RELEASE_PROCESS.md

VibeTunnel Release Process

This document explains how to create releases for VibeTunnel, including the relationship between version numbers, release types, and the release script.

Understanding Version Management

Version Sources

1. version.xcconfig - Contains MARKETING_VERSION (e.g., 1.0.0-beta.7)
2. web/package.json - Must match the marketing version
3. Release script parameters - Used for validation and GitHub release metadata

Key Concept: Version vs Release Type

The release script does NOT modify the version string based on your parameters. Instead:

• The version comes from version.xcconfig
• Script parameters validate that your intent matches the configured version
• For pre-releases, the version must already include the suffix (e.g., -beta.7)

Release Types

Stable Release

# version.xcconfig must have: MARKETING_VERSION = 1.0.0
./scripts/release.sh stable

Beta Release

# version.xcconfig must have: MARKETING_VERSION = 1.0.0-beta.7
./scripts/release.sh beta 7

Alpha Release

# version.xcconfig must have: MARKETING_VERSION = 1.0.0-alpha.2
./scripts/release.sh alpha 2

Release Candidate

# version.xcconfig must have: MARKETING_VERSION = 1.0.0-rc.1
./scripts/release.sh rc 1

Pre-Release Workflow

1. Update version.xcconfig first:

   MARKETING_VERSION = 1.0.0-beta.7
   CURRENT_PROJECT_VERSION = 170
   

2. Update web/package.json to match:

   "version": "1.0.0-beta.7"
   

3. Update CHANGELOG.md with release notes

4. Commit these changes:

   git add mac/VibeTunnel/version.xcconfig web/package.json CHANGELOG.md
   git commit -m "Prepare for v1.0.0-beta.7 release"
   git push
   

5. Run the release script with matching parameters:

   cd mac
   ./scripts/release.sh beta 7
   

Common Mistakes

❌ Wrong: Running release with just a number

./scripts/release.sh 7  # This treats "7" as an unknown release type

❌ Wrong: Mismatched parameters

# version.xcconfig has: 1.0.0-beta.7
./scripts/release.sh beta 8  # Error: expects beta.8 but version has beta.7

✅ Correct: Parameters match the version

# version.xcconfig has: 1.0.0-beta.7
./scripts/release.sh beta 7  # Success!

Dry Run Mode

Test your release without making changes:

./scripts/release.sh beta 7 --dry-run

This will:

• Show what version would be released
• Validate all preconditions
• Display what actions would be taken
• NOT modify any files or create releases

Release Script Actions

The release script automates:

1. Validation

   • Ensures clean git state
   • Verifies version consistency
   • Checks signing certificates
   • Validates build numbers

2. Building

   • Cleans build artifacts
   • Builds universal binary
   • Sets IS_PRERELEASE_BUILD flag appropriately

3. Signing & Notarization

   • Code signs the app
   • Submits for Apple notarization
   • Waits for approval

4. Distribution

   • Creates signed DMG
   • Generates GitHub release
   • Updates appcast XML files
   • Commits and pushes changes

Version Numbering Guidelines

• Stable: MAJOR.MINOR.PATCH (e.g., 1.0.0, 1.1.0, 2.0.0)
• Beta: MAJOR.MINOR.PATCH-beta.N (e.g., 1.0.0-beta.1)
• Alpha: MAJOR.MINOR.PATCH-alpha.N (e.g., 1.0.0-alpha.1)
• RC: MAJOR.MINOR.PATCH-rc.N (e.g., 1.0.0-rc.1)

Build numbers must always increment, even across different release types.

Troubleshooting

"Version already contains pre-release suffix"

This is a warning, not an error. It means the script detected that version.xcconfig already has the correct suffix. The release will proceed normally.

"Not up to date with origin/main"

Pull the latest changes:

git pull --rebase origin main

"Build number X already exists"

Increment the build number in version.xcconfig.

Script times out

The release process can take 10-15 minutes due to notarization. Use a longer timeout or run in a persistent terminal session.

Resume Failed Releases

If a release fails partway through:

./scripts/release-resume.sh

This will pick up where the release left off, skipping completed steps.