Krow-workspace/RELEASE_QUICK_REFERENCE.md

# Release Quick Reference Card

**Print this and pin it to your desk! 📌**

---

## ⚡ Quick Commands

### View All Tags
```bash
git tag -l "*" --sort=-version:refname
```

### View Tags for One Product
```bash
git tag -l "staff-mobile/*" --sort=-version:refname
```

### Create a Tag
```bash
git tag -a staff-mobile/dev-v0.2.0 -m "Staff Mobile v0.2.0"
git push origin staff-mobile/dev-v0.2.0
```

### See What's in a Tag
```bash
git show staff-mobile/prod-v0.1.0
git log staff-mobile/prod-v0.1.0 -5 --oneline
```

### Delete a Tag
```bash
git tag -d staff-mobile/dev-v0.1.0      # Local
git push origin --delete staff-mobile/dev-v0.1.0  # Remote
```

---

## 🏷️ Tag Naming Format

```
<product>/<environment>-v<major>.<minor>.<patch>

Examples:
  staff-mobile/dev-v0.2.0
  client-mobile/staging-v0.2.0
  web-dashboard/prod-v1.0.0
  command-api/prod-v0.1.1
```

**Products:**
- `staff-mobile` / `client-mobile`
- `web-dashboard`
- `command-api` / `core-api`
- `dataconnect`

**Environments:**
- `dev` (development, unstable)
- `staging` (pre-production, testing)
- `prod` (production, stable)

---

## 📝 Checklist: Before You Tag

- [ ] Code review completed
- [ ] All tests passing locally
- [ ] CHANGELOG.md updated
- [ ] Version numbers updated in:
  - [ ] `apps/mobile/apps/*/pubspec.yaml` (if mobile)
  - [ ] `apps/web/package.json` (if web)
  - [ ] `backend/*/package.json` (if backend)
  - [ ] `codemagic.yaml` (if mobile)
- [ ] Committed and pushed changes
- [ ] Ready to merge release branch

---

## 🚀 Create a Release (Quick Steps)

```
1. Update version numbers
   (See "Version File Locations" below)

2. Update CHANGELOG.md
   Add line at top with date and version

3. Commit & push
   git commit -m "chore: bump to v0.2.0"
   git push origin release/branch-name

4. Create tag
   git tag -a product/env-v0.2.0 -m "Description"
   git push origin product/env-v0.2.0

5. Create GitHub Release
   Go to Releases → Draft new release
   Select tag → Fill in details → Publish

6. Deploy
   (Follow your deployment script)

7. Monitor
   Check logs for 24 hours
```

---

## 📍 Version File Locations

**Quick edit list for version bumps:**

### Mobile (Staff & Client)
- [ ] `apps/mobile/apps/staff_app/pubspec.yaml`
- [ ] `apps/mobile/apps/client_app/pubspec.yaml`

Format: `version: X.Y.Z+N` (N = build number)

### Web
- [ ] `apps/web/package.json`

Format: `"version": "X.Y.Z"`

### Backend
- [ ] `backend/command-api/package.json`
- [ ] `backend/core-api/package.json`

Format: `"version": "X.Y.Z"`

### CI/CD
- [ ] `codemagic.yaml`

Format: `build_version: "X.Y.Z"`

**Also update CHANGELOG.md!**

---

## 🔄 Release Timeline At-a-Glance

| Stage | Duration | Environment | Status | Next Step |
|-------|----------|-------------|--------|-----------|
| **Feature Dev** | 1-2 weeks | Local | 👨‍💻 In progress | Code review |
| **Code Review** | 1-3 days | GitHub | 👀 Reviewing | Merge to main |
| **Dev Release** | Same day | Dev env | ✅ Deployed | Weekly |
| **Staging Release** | 1 week | Staging | 🧪 Testing | QA sign-off |
| **Prod Release** | 2-3 hours | Production | 🚀 Deploying | 24h monitoring |

---

## 📞 Common Tasks

### I want to release Staff Mobile v0.2.0
```bash
git checkout -b release/staff-mobile-v0.2.0
# Edit: apps/mobile/apps/staff_app/pubspec.yaml (0.1.0 → 0.2.0)
# Edit: CHANGELOG.md (add entry)
git add .
git commit -m "chore: staff mobile v0.2.0"
git push origin release/staff-mobile-v0.2.0
# Create PR, get approved, merge
git tag -a staff-mobile/dev-v0.2.0 -m "Staff Mobile v0.2.0"
git push origin staff-mobile/dev-v0.2.0
```

### I found a critical bug in production
```bash
git checkout -b hotfix/staff-mobile-v0.1.1 staff-mobile/prod-v0.1.0
# Fix the bug
# Bump version 0.1.0 → 0.1.1 in pubspec.yaml
git commit -m "fix: [critical issue]"
git tag -a staff-mobile/prod-v0.1.1 -m "Hotfix: [issue]"
git push origin staff-mobile/prod-v0.1.1
# Deploy immediately, monitor 24h
```

### I want to see all production versions
```bash
git tag -l "*/prod-v*" --sort=-version:refname
```

### I want to compare two versions
```bash
git log staff-mobile/prod-v0.1.0...staff-mobile/prod-v0.2.0 --oneline
```

---

## 🎯 Deployment Order (Multi-Product Release)

Always deploy in this order:

1. **DataConnect** (if schema changed)
2. **Command API** + **Core API** (can be parallel)
3. **Web Dashboard**
4. **Staff Mobile** + **Client Mobile** (can be parallel)

Verify each step completes before moving to next.

---

## ⚠️ Red Flags 🚫

**DON'T tag if:**
- ❌ Tests are failing
- ❌ Code review not approved
- ❌ CHANGELOG not updated
- ❌ Version numbers not bumped
- ❌ Breaking changes not documented
- ❌ Staging not tested yet
- ❌ Team not notified

**DO tag if:**
- ✅ All tests passing
- ✅ Code reviewed + approved
- ✅ CHANGELOG updated
- ✅ Version numbers consistent
- ✅ Staged and tested
- ✅ Team aware

---

## 🆘 Troubleshoot

**Tag won't push:**
```bash
# Make sure you have push permissions
git config --list | grep remote.origin.url
# Re-authenticate if needed
git credential-osxkeychain erase host=github.com
```

**Wrong tag created:**
```bash
git tag -d wrong-tag
git push origin --delete wrong-tag
git tag -a correct-tag -m "message"
git push origin correct-tag
```

**Need to see what changed:**
```bash
git log v0.1.0..v0.2.0 --oneline
git diff v0.1.0..v0.2.0 -- apps/mobile/
```

---

## 📚 Full Documentation

For complete details, see:
- 📖 [RELEASE_STRATEGY.md](./RELEASE_STRATEGY.md) - Full strategy
- 🔧 [RELEASE_WORKFLOW.md](./RELEASE_WORKFLOW.md) - Step-by-step
- 🚀 [RELEASE_IMPLEMENTATION.md](./RELEASE_IMPLEMENTATION.md) - Setup guide
- 📊 [RELEASE_VISUAL_GUIDE.md](./RELEASE_VISUAL_GUIDE.md) - Diagrams

---

## 📞 Contact

**Release Questions?** Slack: #releases
**Need Help?** Check RELEASE_WORKFLOW.md or ask DevOps team

---

**Last Updated**: 2026-03-05
**Bookmark this page! 🔖**