Krow-workspace/RELEASE_QUICK_REFERENCE.md

Release Quick Reference Card

Print this and pin it to your desk! 📌

---

⚡ Quick Commands

View All Tags

git tag -l "*" --sort=-version:refname

View Tags for One Product

git tag -l "staff-mobile/*" --sort=-version:refname

Create a Tag

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

git show staff-mobile/prod-v0.1.0
git log staff-mobile/prod-v0.1.0 -5 --oneline

Delete a Tag

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

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

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

git tag -l "*/prod-v*" --sort=-version:refname

I want to compare two versions

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:

# 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:

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:

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 - Full strategy
• 🔧 RELEASE_WORKFLOW.md - Step-by-step
• 🚀 RELEASE_IMPLEMENTATION.md - Setup guide
• 📊 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! 🔖