Gmacko Release Preparation

Prepare release artifacts including changelog, release notes, and environment verification.

When to Use

• QA verification is complete (APPROVED)
• Ready to deploy to staging or production
• Need to generate release notes
• Cutting a new version

Prerequisites

• QA handoff exists and is APPROVED
• All related PRs are merged
• Branch is ready for deployment

Workflow

digraph release_prepare {
    rankdir=TB;
    node [shape=box];
    
    start [label="Start Preparation" shape=ellipse];
    gather [label="1. Gather Changes"];
    version [label="2. Determine Version"];
    notes [label="3. Generate Release Notes"];
    changelog [label="4. Update CHANGELOG"];
    env [label="5. Verify Environment"];
    migration [label="6. Check Migrations"];
    checklist [label="7. Run Release Checklist"];
    summary [label="8. Create Release Summary"];
    done [label="Ready for Deploy" shape=ellipse];
    
    start -> gather -> version -> notes;
    notes -> changelog -> env -> migration;
    migration -> checklist -> summary -> done;
}

Execution Steps

Step 1: Gather Changes

Collect all changes since last release:

# Get last release tag
LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")

# List commits since last release
if [ -n "$LAST_TAG" ]; then
    git log ${LAST_TAG}..HEAD --oneline --no-merges
else
    git log --oneline -20
fi

# List merged PRs
gh pr list --state merged --limit 20 --json number,title,labels

Categorize changes:

• Features: New functionality
• Fixes: Bug fixes
• Improvements: Enhancements
• Breaking: Breaking changes
• Docs: Documentation updates
• Chores: Maintenance/tooling

Step 2: Determine Version

Follow semantic versioning:

MAJOR.MINOR.PATCH

MAJOR: Breaking changes
MINOR: New features (backwards compatible)
PATCH: Bug fixes (backwards compatible)

Ask user:

Based on the changes, I recommend version [X.Y.Z].

Changes include:
- [N] new features
- [N] bug fixes
- [N] breaking changes

Is this version correct, or would you like to specify?

Step 3: Generate Release Notes

Create release notes:

# Release Notes: v[X.Y.Z]

**Release Date**: [YYYY-MM-DD]
**Environment**: [staging/production]

## Highlights

[1-2 sentence summary of the most important changes]

## What's New

### Features
- **[Feature Name]**: [Brief description] (#123)
- **[Feature Name]**: [Brief description] (#124)

### Improvements
- [Improvement description] (#125)

### Bug Fixes
- Fixed [issue description] (#126)
- Fixed [issue description] (#127)

## Breaking Changes

[If any, describe migration steps]

## Dependencies

- Updated [package] from X to Y
- Added [new package] for [purpose]

## Contributors

- @username
- @username

## Full Changelog

[Link to compare: previous...current]

Step 4: Update CHANGELOG

Update CHANGELOG.md (if it exists) or docs/ai/CHANGELOG.md:

## [X.Y.Z] - YYYY-MM-DD

### Added
- Feature description (#123)

### Changed
- Change description (#124)

### Fixed
- Fix description (#125)

### Removed
- Removal description (#126)

Step 5: Verify Environment

Check target environment is ready:

# For Vercel (web)
vercel env ls --environment production

# Check required env vars are set
REQUIRED_VARS=(
    "DATABASE_URL"
    "CLERK_SECRET_KEY"
    "NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY"
)

for var in "${REQUIRED_VARS[@]}"; do
    vercel env ls --environment production | grep -q "$var" && \
        echo "OK: $var" || echo "MISSING: $var"
done

For mobile (EAS):

# Check EAS configuration
eas config --platform ios
eas config --platform android

# Verify credentials
eas credentials --platform ios
eas credentials --platform android

Step 6: Check Migrations

If database changes are included:

## Migration Check

### Pending Migrations
- [ ] `20250105_add_feature_table.sql`

### Migration Plan
1. Backup production database
2. Apply migration in staging first
3. Verify data integrity
4. Apply to production during low-traffic window

### Rollback Plan

-- Rollback script DROP TABLE IF EXISTS newtable; ALTER TABLE existingtable DROP COLUMN new_column;

### Data Impact
- Rows affected: ~[N]
- Estimated duration: [X] seconds
- Downtime required: No

Step 7: Run Release Checklist

Use the release checklist from docs/ai/checklists/release-checklist.md:

## Pre-Release Checklist

### Code Quality
- [ ] All PRs merged
- [ ] `pnpm typecheck` passes
- [ ] `pnpm lint` passes
- [ ] `pnpm build` succeeds

### Testing
- [ ] QA verification complete
- [ ] No blocking issues
- [ ] Regression tests passed

### Documentation
- [ ] Release notes written
- [ ] CHANGELOG updated
- [ ] Migration guide ready (if needed)

### Environment
- [ ] Env vars configured
- [ ] Third-party services ready
- [ ] SSL certificates valid

Step 8: Create Release Summary

Write docs/ai/releases/[date]-v[version].md:

# Release: v[X.Y.Z]

## Metadata
- **Version**: X.Y.Z
- **Date**: YYYY-MM-DD
- **Tag**: v[X.Y.Z]
- **Prepared by**: AI Assistant

## Status
- [ ] Staging deployed
- [ ] Staging verified
- [ ] Production deployed
- [ ] Production verified

## Changes Summary

| Type | Count |
|------|-------|
| Features | X |
| Fixes | Y |
| Improvements | Z |

### Key Changes
1. [Most important change]
2. [Second most important]
3. [Third most important]

## PRs Included
- #123: [Title]
- #124: [Title]
- #125: [Title]

## Issues Closed
- #100: [Title]
- #101: [Title]

## Environment Verification
- [x] Production env vars set
- [x] Database migrations ready
- [x] Third-party services configured

## Deployment Commands

### Web (Vercel)

Automatic via git push to main

git push origin main

Or manual

vercel --prod

### Mobile (EAS)

Build

eas build --platform all --profile production

Submit

eas submit --platform ios eas submit --platform android

## Rollback Plan

### Web

vercel rollback

### Database

Run rollback migration

pnpm db:rollback

## Post-Deployment
- [ ] Smoke test production
- [ ] Monitor Sentry for errors
- [ ] Check analytics events
- [ ] Update status page

---

**Prepared by**: AI Assistant
**Approved by**: [Pending]

Output

Present summary to user:

RELEASE PREPARATION COMPLETE
============================

Version: v[X.Y.Z]
Changes: [N] features, [N] fixes, [N] improvements
Breaking Changes: [Yes/No]

Artifacts Created:
- docs/ai/releases/[date]-v[version].md
- Release notes (ready for GitHub release)
- CHANGELOG updated

Environment Status:
- Web (Vercel): READY
- Mobile (EAS): READY
- Database: [N] pending migrations

Next Steps:
1. Review release summary
2. Run `gmacko-release-deploy-web` for Vercel deployment
3. Run `gmacko-release-deploy-mobile` for EAS builds (if applicable)

Proceed with deployment?

Red Flags

Integration

• Input: Version number (or auto-determine), target environment
• References: QA handoffs, merged PRs, git history
• Output: Release summary, changelog updates, release notes
• Next: gmacko-release-deploy-web or gmacko-release-deploy-mobile