mirror of
https://github.com/samsonjs/vibetunnel.git
synced 2026-04-05 11:15:57 +00:00
Add comprehensive release guide with troubleshooting
- Quick reference commands for releases - Pre-release checklist with all version files - Troubleshooting section for common issues - Documentation of new tools (progress monitor, health check) - Best practices based on beta.13 experience - Manual recovery procedures
This commit is contained in:
Peter Steinberger
parent
9e825ff21e
commit
754f06afb8
1 changed files with 220 additions and 0 deletions
220
mac/docs/RELEASE_GUIDE.md
Normal file
220
mac/docs/RELEASE_GUIDE.md
Normal file
|
|
@ -0,0 +1,220 @@
|
|||
# VibeTunnel Release Guide - Quick Reference
|
||||
|
||||
This guide provides a streamlined release process based on lessons learned from beta.13.
|
||||
|
||||
## 🚀 Quick Release Commands
|
||||
|
||||
```bash
|
||||
# 1. Pre-release health check
|
||||
./scripts/release-health-check.sh
|
||||
|
||||
# 2. Set environment variables
|
||||
export SPARKLE_ACCOUNT="VibeTunnel"
|
||||
export CI=false
|
||||
export SKIP_NODE_CHECK=false
|
||||
|
||||
# 3. Run the release
|
||||
./scripts/release.sh beta 14 # For next beta
|
||||
|
||||
# 4. Monitor progress in another terminal
|
||||
./scripts/release-progress.sh
|
||||
|
||||
# 5. If interrupted, resume
|
||||
./scripts/release.sh --resume
|
||||
```
|
||||
|
||||
## 📋 Pre-Release Checklist
|
||||
|
||||
Before starting any release:
|
||||
|
||||
### 1. Version Numbers
|
||||
- [ ] Update `mac/VibeTunnel/version.xcconfig`:
|
||||
- `MARKETING_VERSION = 1.0.0-beta.14`
|
||||
- `CURRENT_PROJECT_VERSION = 203` (increment from last)
|
||||
- [ ] Update `web/package.json` to match
|
||||
- [ ] Update `web/package.npm.json` to match
|
||||
- [ ] Update `CHANGELOG.md` with release notes
|
||||
|
||||
### 2. Environment Setup
|
||||
```bash
|
||||
# Required environment variables
|
||||
export SPARKLE_ACCOUNT="VibeTunnel"
|
||||
export CI=false
|
||||
export SKIP_NODE_CHECK=false
|
||||
|
||||
# Notarization credentials (if not already set)
|
||||
export APP_STORE_CONNECT_KEY_ID="your_key_id"
|
||||
export APP_STORE_CONNECT_ISSUER_ID="your_issuer_id"
|
||||
export APP_STORE_CONNECT_API_KEY_P8="-----BEGIN PRIVATE KEY-----
|
||||
your_private_key_content
|
||||
-----END PRIVATE KEY-----"
|
||||
```
|
||||
|
||||
### 3. Clean State
|
||||
```bash
|
||||
# Ensure clean git state
|
||||
git status # Should be clean
|
||||
git pull --rebase origin main
|
||||
|
||||
# Run health check
|
||||
./scripts/release-health-check.sh
|
||||
```
|
||||
|
||||
## 🔧 Troubleshooting
|
||||
|
||||
### Node.js Detection Issues
|
||||
If the build fails with "Node.js is required":
|
||||
```bash
|
||||
# Test Node.js detection
|
||||
./scripts/check-node-simple.sh
|
||||
|
||||
# If using nvm, ensure it's loaded
|
||||
source ~/.nvm/nvm.sh
|
||||
nvm use 20 # or your version
|
||||
|
||||
# Create symlinks if needed (requires sudo)
|
||||
sudo ln -s $(which node) /usr/local/bin/node
|
||||
sudo ln -s $(which pnpm) /usr/local/bin/pnpm
|
||||
```
|
||||
|
||||
### Release Script Timeouts
|
||||
The release process can take 20-30 minutes:
|
||||
- Build: 2-5 minutes
|
||||
- Notarization: 5-15 minutes
|
||||
- DMG creation: 1-2 minutes
|
||||
|
||||
If it times out:
|
||||
```bash
|
||||
# Check current status
|
||||
./scripts/release-progress.sh
|
||||
|
||||
# Resume from last step
|
||||
./scripts/release.sh --resume
|
||||
```
|
||||
|
||||
### Manual Recovery
|
||||
If the release script fails after notarization:
|
||||
|
||||
```bash
|
||||
# 1. Create GitHub release manually
|
||||
./scripts/generate-release-notes.sh 1.0.0-beta.14 > notes.md
|
||||
gh release create "v1.0.0-beta.14" \
|
||||
--title "VibeTunnel 1.0.0-beta.14" \
|
||||
--notes-file notes.md \
|
||||
--prerelease \
|
||||
build/VibeTunnel-*.dmg \
|
||||
build/VibeTunnel-*.zip
|
||||
|
||||
# 2. Sign DMG for Sparkle
|
||||
sign_update -f private/sparkle_ed_private_key \
|
||||
build/VibeTunnel-1.0.0-beta.14.dmg \
|
||||
--account VibeTunnel
|
||||
|
||||
# 3. Update appcast manually
|
||||
# Add the signature to appcast-prerelease.xml
|
||||
# Then commit and push
|
||||
git add ../appcast-prerelease.xml
|
||||
git commit -m "Update appcast for v1.0.0-beta.14"
|
||||
git push
|
||||
```
|
||||
|
||||
## 📊 New Tools
|
||||
|
||||
### Release Progress Monitor
|
||||
Shows real-time release progress with visual indicators:
|
||||
```bash
|
||||
./scripts/release-progress.sh
|
||||
```
|
||||
|
||||
Features:
|
||||
- Step-by-step progress tracking
|
||||
- Duration for each step
|
||||
- Idle time warnings
|
||||
- Artifact status
|
||||
|
||||
### Release Health Check
|
||||
Comprehensive pre-release validation:
|
||||
```bash
|
||||
./scripts/release-health-check.sh
|
||||
```
|
||||
|
||||
Checks:
|
||||
- Git status and branch
|
||||
- Environment variables
|
||||
- Build tools availability
|
||||
- Code signing certificates
|
||||
- Version synchronization
|
||||
- Disk space
|
||||
- Appcast validity
|
||||
|
||||
### Simplified Node.js Check
|
||||
More robust Node.js detection:
|
||||
```bash
|
||||
./scripts/check-node-simple.sh
|
||||
```
|
||||
|
||||
## 🎯 Best Practices
|
||||
|
||||
1. **Always run health check first** - Catches issues before they cause failures
|
||||
2. **Use progress monitor** - Keep track of long-running operations
|
||||
3. **Set all environment variables** - Prevents mid-release failures
|
||||
4. **Keep versions synchronized** - Update all version files before starting
|
||||
5. **Document in CHANGELOG.md** - Required for release notes generation
|
||||
6. **Don't run in background** - Use screen/tmux if needed, but keep foreground
|
||||
|
||||
## 📝 Version Management
|
||||
|
||||
### Version Files to Update
|
||||
1. `mac/VibeTunnel/version.xcconfig` - Source of truth
|
||||
2. `web/package.json` - Must match macOS version
|
||||
3. `web/package.npm.json` - For npm package release
|
||||
4. `CHANGELOG.md` - Release notes
|
||||
|
||||
### Build Number Rules
|
||||
- Must increment for EVERY release
|
||||
- Must be unique across all releases
|
||||
- Sparkle uses build numbers, not version strings
|
||||
- Check existing: `grep '<sparkle:version>' ../appcast*.xml`
|
||||
|
||||
## 🚨 Common Issues
|
||||
|
||||
### "Uncommitted changes detected"
|
||||
- Commit all changes before releasing
|
||||
- Or stash temporarily: `git stash`
|
||||
|
||||
### "Build number already exists"
|
||||
- Increment CURRENT_PROJECT_VERSION in version.xcconfig
|
||||
- Must be higher than all previous releases
|
||||
|
||||
### "Version mismatch"
|
||||
- Ensure web/package.json matches mac version
|
||||
- Run health check to verify
|
||||
|
||||
### DMG stuck volumes
|
||||
```bash
|
||||
# List stuck volumes
|
||||
ls /Volumes/VibeTunnel*
|
||||
|
||||
# Force unmount
|
||||
for vol in /Volumes/VibeTunnel*; do
|
||||
hdiutil detach "$vol" -force
|
||||
done
|
||||
```
|
||||
|
||||
## 📚 Summary
|
||||
|
||||
The improved release process provides:
|
||||
- Better error handling with environment variable defaults
|
||||
- Visual progress tracking
|
||||
- Comprehensive pre-flight validation
|
||||
- Clear recovery procedures
|
||||
- Simplified troubleshooting
|
||||
|
||||
For the smoothest release experience:
|
||||
1. Run health check
|
||||
2. Set environment variables
|
||||
3. Use the standard release script
|
||||
4. Monitor with progress tool
|
||||
5. Resume if interrupted
|
||||
|
||||
The release should complete in 20-30 minutes with clear visibility into each step.
|
||||
Loading…
Reference in a new issue