diff --git a/RELEASE_IMPLEMENTATION.md b/RELEASE_IMPLEMENTATION.md deleted file mode 100644 index 3af3c020..00000000 --- a/RELEASE_IMPLEMENTATION.md +++ /dev/null @@ -1,509 +0,0 @@ -# Release Strategy Implementation Guide - -This guide walks you through implementing the tagging and release strategy for KROW Workforce. - ---- - -## πŸ“ Phase 1: Initial Setup (Do This First) - -### Step 1: Review and Approve Strategy - -1. Read [RELEASE_STRATEGY.md](./RELEASE_STRATEGY.md) -2. Get team feedback -3. Customize if needed (adjust cadence, naming, etc.) -4. Commit to this approach - -### Step 2: Verify Current State - -Check current versions of all products: - -```bash -# Mobile -cat apps/mobile/apps/staff_app/pubspec.yaml | grep "^version:" -cat apps/mobile/apps/client_app/pubspec.yaml | grep "^version:" - -# Web -cat apps/web/package.json | grep '"version"' - -# Backend -cat backend/command-api/package.json | grep '"version"' -cat backend/core-api/package.json | grep '"version"' -``` - -Current expected state: -``` -Staff Mobile: 0.1.0+? -Client Mobile: 0.1.0+? -Web Dashboard: 0.0.0 -Command API: 0.1.0 -Core API: 0.1.0 -``` - -### Step 3: Create Initial Dev Tags - -Create retrospective tags for the current state. This establishes a baseline. - -```bash -# Navigate to repo -cd /Users/achintha/Documents/GitHub/krow-workforce - -# Create tags for current development versions -# (These mark the current checkpoint, not retrospective releases) - -git tag -a staff-mobile/dev-v0.1.0 -m "Staff Mobile v0.1.0 - Initial development release" -git tag -a client-mobile/dev-v0.1.0 -m "Client Mobile v0.1.0 - Initial development release" -git tag -a web-dashboard/dev-v0.0.0 -m "Web Dashboard v0.0.0 - Pre-release" -git tag -a command-api/dev-v0.1.0 -m "Command API v0.1.0 - Initial development release" -git tag -a core-api/dev-v0.1.0 -m "Core API v0.1.0 - Initial development release" - -# Push all tags to remote -git push origin --tags - -# Verify tags were created -git tag -l "*" --sort=-version:refname -``` - -Expected output: -``` -core-api/dev-v0.1.0 -command-api/dev-v0.1.0 -client-mobile/dev-v0.1.0 -staff-mobile/dev-v0.1.0 -web-dashboard/dev-v0.0.0 -``` - ---- - -## πŸ“ Phase 2: GitHub Configuration - -### Step 1: Enable Branch Protection for Production Tags - -1. Go to your GitHub repo β†’ Settings β†’ Branches -2. Click "Add rule" -3. Configure as follows: - -``` -Branch name pattern: */prod-v* - -Require a pull request before merging: βœ… ON -Require approvals: βœ… ON (1+ approvals) -Dismiss stale pull request approvals: βœ… ON -Require status checks to pass: βœ… ON -Require branches to be up to date before merging: βœ… ON -Include administrators: βœ… ON -Allow force pushes: ❌ OFF -Allow deletions: ❌ OFF -``` - -4. Click "Create" - -### Step 2: Configure Required Status Checks - -Status checks that must pass before merging: -- `build / test` - Unit and integration tests -- `build / lint` - Code quality checks -- `build / security-scan` - Security validation - -(These should already exist from your CI/CD pipeline) - -### Step 3: Setup Release Notes Template - -1. Go to Settings β†’ Releases β†’ Set up a release -2. Add this template: - -```markdown -## Release Notes: [Product] v[Version] - -**Release Date**: [Date] -**Environment**: [dev/staging/prod] - -### 🎯 What's New - -### ✨ Features -- Feature 1 -- Feature 2 - -### πŸ”§ Improvements -- Improvement 1 -- Improvement 2 - -### πŸ› Bug Fixes -- Bug fix 1 -- Bug fix 2 - -### πŸ“¦ Dependencies & Compatibility - -**Requires:** -- Backend API v[X.X.X] or higher -- [Other dependencies] - -**Compatible with:** -- [Previous version compatibility] - -### πŸ“₯ Installation - -[Download links and installation instructions] - -### ⚠️ Known Issues & Workarounds - -- Issue 1: [description] (Workaround: ...) - -### πŸ”„ Migration Guide - -[Steps for upgrading from previous version] - -### πŸ“ž Support - -For issues: support@krow-workforce.com -``` - ---- - -## πŸ“ Phase 3: CI/CD Integration (CodeMagic) - -### Update CodeMagic for Automated Tagging (Optional) - -Edit `codemagic.yaml` to automatically create tags on successful builds: - -```yaml -workflows: - mobile-client-build: - on: - push: - branches: - - main - # ... existing config ... - - # Add this section - on_success: - - | - if [ "$CI_BRANCH" = "main" ]; then - VERSION=$(grep "^version:" apps/mobile/apps/client_app/pubspec.yaml | cut -d' ' -f2) - git tag -a client-mobile/dev-${VERSION} \ - -m "Client Mobile ${VERSION} - Development build from CodeMagic" - git push origin client-mobile/dev-${VERSION} - fi -``` - -(Optional - can be done manually initially) - ---- - -## πŸ“ Phase 4: Create Release Documentation - -### Copy Release Checklist Template - -Create a file for release planning: - -```bash -mkdir -p docs/releases -``` - -Create `docs/releases/RELEASE_TEMPLATE.md`: - -```markdown -# Release Plan: [Product] v[Version] - -**Status**: Draft / In Progress / Completed -**Target Date**: [Date] -**Release Manager**: [Name] - -## Scope - -[Description of features/fixes in this release] - -## Pre-Release Tasks (48h before) - -- [ ] All PRs merged and code reviewed -- [ ] All tests green (unit, integration, E2E) -- [ ] No lint/type errors -- [ ] Mobile builds succeed on CodeMagic -- [ ] Performance benchmarks acceptable -- [ ] Security scan passed -- [ ] CHANGELOG.md updated with all changes -- [ ] Documentation updated -- [ ] Staging environment prepared for testing - -## Release Day Tasks - -- [ ] Create release branch: `release/[product]-v[version]` -- [ ] Update version in all relevant files -- [ ] Commit and push release branch -- [ ] Create git tags (staging) -- [ ] Deploy to staging environment -- [ ] Run smoke tests -- [ ] Get sign-off from product owner - -## Post-Release Tasks (24h after) - -- [ ] Monitor error logs -- [ ] Verify all features work end-to-end -- [ ] Performance is acceptable -- [ ] Create production tags -- [ ] Deploy to production -- [ ] Final verification -- [ ] Create GitHub Release page -- [ ] Announce release to users - -## Rollback Plan (if needed) - -``` -Issue Found: [description] -Severity: Critical / High / Medium -Action: Rollback to v[previous-version] -Hotfix: [version bump plan] -``` - -## Outcomes - -**Release Date**: [Actual date] -**Status**: βœ… Successful / ⚠️ Issues / 🚫 Rolled back - -[Additional notes] -``` - ---- - -## πŸ“ Phase 5: Team Training - -### Create Runbook for Team - -Share [RELEASE_WORKFLOW.md](./RELEASE_WORKFLOW.md) with your team - -### Conduct Training Session - -**Agenda (30 minutes):** -1. Explain versioning strategy (5 min) -2. Walk through release workflow (10 min) -3. Demo: Create a test tag (10 min) -4. Q&A (5 min) - -### Sample Demo Commands - -```bash -# Everyone runs these to practice - -# 1. See existing tags -git tag -l - -# 2. Create a test tag (won't push) -git tag -a test/demo-v0.0.1 -m "Demo tag for training" - -# 3. View tag details -git show test/demo-v0.0.1 - -# 4. Delete test tag -git tag -d test/demo-v0.0.1 -``` - ---- - -## πŸ“ Phase 6: First Real Release - -### Plan Your First Staging Release - -Let's do: **Staff Mobile v0.2.0** (next development version) - -### 1. Prepare Changes - -```bash -# Make your feature/fix commits normally -git checkout main -git pull origin main - -# Create feature branches as usual -git checkout -b feature/some-feature -# ... make changes ... -git commit -m "feat(staff-mobile): Add new feature" - -git push origin feature/some-feature -# Create PR, review, merge -``` - -### 2. Create Release Branch - -```bash -# Start release -git checkout main -git pull origin main -git checkout -b release/staff-mobile-v0.2.0 -``` - -### 3. Bump Version - -```bash -# Edit: apps/mobile/apps/staff_app/pubspec.yaml -# Change: version: 0.1.0+5 β†’ version: 0.2.0+6 - -nano apps/mobile/apps/staff_app/pubspec.yaml -``` - -### 4. Update CHANGELOG - -```bash -nano CHANGELOG.md - -# Add at top: -# | 2026-03-05 | Staff Mobile 0.2.0 | Feature: [description] | -``` - -### 5. Commit & Tag - -```bash -git add . -git commit -m "chore(staff-mobile): bump version to 0.2.0" -git push origin release/staff-mobile-v0.2.0 - -# Create and push tag -git tag -a staff-mobile/staging-v0.2.0 -m "Staff Mobile v0.2.0 - Staging release" -git push origin staff-mobile/staging-v0.2.0 - -# Verify -git tag -l "staff-mobile/*" --sort=-version:refname -``` - -### 6. Deploy & Test - -```bash -# Deploy to staging environment -# (Use your deployment scripts or manual process) - -# Run tests -make test-mobile-staff - -# Get team QA approval -``` - -### 7. Promote to Production - -```bash -# Create production tag -git tag -a staff-mobile/prod-v0.2.0 -m "Staff Mobile v0.2.0 - Production release" -git push origin staff-mobile/prod-v0.2.0 - -# Deploy to production -# (Use your deployment scripts) -``` - -### 8. Create GitHub Release - -1. Go to https://github.com/[your-org]/krow-workforce/releases -2. Click "Draft a new release" -3. Fill in: - - Tag: `staff-mobile/prod-v0.2.0` - - Title: `Staff Mobile v0.2.0` - - Description: Copy from CHANGELOG - - Add APK/AAB as attachments (if available) -4. Click "Publish release" - ---- - -## πŸ“‹ Communication Plan - -### For Each Release - -1. **Announcement** (release day) - ``` - πŸ“± Staff Mobile v0.2.0 released! - - Includes: [feature summary] - Available: [iOS/Android app stores] - ``` - -2. **Status Updates** (during staging QA) - ``` - πŸ”„ Staff Mobile v0.2.0 in staging for testing - Expected production release: [date] - ``` - -3. **Post-Release** (24h after) - ``` - βœ… Staff Mobile v0.2.0 now in production - All systems normal. No issues reported. - ``` - -4. **If Issues** - ``` - ⚠️ Staff Mobile v0.2.0 - Hotfix in progress - Rollback to v0.1.0 - No impact to users - ETA for fix: [time] - ``` - ---- - -## πŸ”§ Troubleshooting - -### Problem: Tag Already Exists - -```bash -# If you try to create a tag that exists: -error: **/prod-v0.1.0 already exists - -# Solution: Delete and recreate -git tag -d staff-mobile/dev-v0.1.0 -git push origin --delete staff-mobile/dev-v0.1.0 -git tag -a staff-mobile/dev-v0.1.0 -m "New message" -git push origin staff-mobile/dev-v0.1.0 -``` - -### Problem: Can't Push Tags - -```bash -# Error: remote permission denied - -# Solution: Ensure you have push access -git credential-osxkeychain erase host=github.com # Re-authenticate -# Then try again -git push origin --tags -``` - -### Problem: Version Not Updated Everywhere - -```bash -# Verify all locations have same version -grep -r "0.2.0" apps/mobile/apps/*/pubspec.yaml -grep '"0.2.0"' apps/web/package.json -grep '"0.2.0"' backend/*/package.json -grep 'build_version: "0.2.0"' codemagic.yaml - -# Update any missing locations -``` - ---- - -## βœ… Validation Checklist - -After implementing this strategy, verify: - -- [ ] Initial dev tags created (v0.1.0 for all products) -- [ ] GitHub branch protection configured for prod tags -- [ ] Release template documented in repo -- [ ] Team trained on release process -- [ ] CHANGELOG.md in place and tracked -- [ ] First staging release completed successfully -- [ ] GitHub Release page created for first release -- [ ] Communication plan working - ---- - -## 🎯 Next Steps - -1. βœ… Review RELEASE_STRATEGY.md with team -2. βœ… Complete Phase 1 setup (create initial tags) -3. βœ… Configure GitHub (Phase 2) -4. ⏳ First release (Staff Mobile v0.2.0) planned for [date] -5. ⏳ Establish release cadence (weekly dev, bi-weekly staging, monthly prod) - ---- - -## πŸ“ž Questions? - -Reference documents: -- [RELEASE_STRATEGY.md](./RELEASE_STRATEGY.md) - Full strategy -- [RELEASE_WORKFLOW.md](./RELEASE_WORKFLOW.md) - Step-by-step workflows -- [CHANGELOG.md](./CHANGELOG.md) - Version history - ---- - -**Created**: 2026-03-05 -**Status**: Ready for Implementation diff --git a/RELEASE_INDEX.md b/RELEASE_INDEX.md deleted file mode 100644 index 1874c655..00000000 --- a/RELEASE_INDEX.md +++ /dev/null @@ -1,411 +0,0 @@ -# Release Documentation Index - -**🎯 Start here!** This page helps you find the right document for your needs. - ---- - -## πŸ” Find What You Need - -### "I want to understand the release strategy" -1. Start: [RELEASE_STRATEGY.md](./RELEASE_STRATEGY.md) (15 min read) -2. Visualize: [RELEASE_VISUAL_GUIDE.md](./RELEASE_VISUAL_GUIDE.md) (10 min read) -3. Deep dive: [RELEASE_IMPLEMENTATION.md](./RELEASE_IMPLEMENTATION.md) - -### "I need to perform a release right now" -1. Quick: [RELEASE_QUICK_REFERENCE.md](./RELEASE_QUICK_REFERENCE.md) (2 min scan) -2. Execute: [RELEASE_WORKFLOW.md](./RELEASE_WORKFLOW.md) (find your scenario) -3. Reference: [VERSION_FILES_REFERENCE.md](./VERSION_FILES_REFERENCE.md) (which files to edit) - -### "I'm setting up the release process for the first time" -1. Follow: [RELEASE_IMPLEMENTATION.md](./RELEASE_IMPLEMENTATION.md) (Phase by phase) -2. Configure: [RELEASE_STRATEGY.md](./RELEASE_STRATEGY.md) β†’ GitHub section -3. Train: Use [RELEASE_VISUAL_GUIDE.md](./RELEASE_VISUAL_GUIDE.md) for team - -### "I need to train my team" -1. Overview: [RELEASE_STRATEGY.md](./RELEASE_STRATEGY.md) -2. Visuals: [RELEASE_VISUAL_GUIDE.md](./RELEASE_VISUAL_GUIDE.md) (show diagrams) -3. Hands-on: Walk through [RELEASE_WORKFLOW.md](./RELEASE_WORKFLOW.md) together -4. Reference: Give each [RELEASE_QUICK_REFERENCE.md](./RELEASE_QUICK_REFERENCE.md) - -### "I'm doing a specific type of release" - -#### **Releasing Staff Mobile v0.2.0 (Single Product)** -1. Steps: [RELEASE_WORKFLOW.md](./RELEASE_WORKFLOW.md) β†’ "Release a single product" -2. Files: [VERSION_FILES_REFERENCE.md](./VERSION_FILES_REFERENCE.md) β†’ "Staff Mobile App" -3. Checklist: [RELEASE_QUICK_REFERENCE.md](./RELEASE_QUICK_REFERENCE.md) β†’ "Pre-tag checklist" - -#### **Coordinated Release All Products v1.0.0** -1. Plan: [RELEASE_STRATEGY.md](./RELEASE_STRATEGY.md) β†’ "Release Cadence" -2. Execute: [RELEASE_WORKFLOW.md](./RELEASE_WORKFLOW.md) β†’ "Multi-Product Coordinated" -3. Deploy: [RELEASE_VISUAL_GUIDE.md](./RELEASE_VISUAL_GUIDE.md) β†’ "Deployment Order" - -#### **Emergency Hotfix (Critical Bug)** -1. Steps: [RELEASE_WORKFLOW.md](./RELEASE_WORKFLOW.md) β†’ "Hotfix Release" -2. Fast: [RELEASE_QUICK_REFERENCE.md](./RELEASE_QUICK_REFERENCE.md) β†’ "Common Tasks" -3. Order: [RELEASE_VISUAL_GUIDE.md](./RELEASE_VISUAL_GUIDE.md) β†’ "Hotfix Flow" - -### "I need to update version numbers" -β†’ [VERSION_FILES_REFERENCE.md](./VERSION_FILES_REFERENCE.md) (Product-by-product guide) - -### "I need git commands" -β†’ [RELEASE_QUICK_REFERENCE.md](./RELEASE_QUICK_REFERENCE.md) β†’ "Quick Commands" - -### "I'm troubleshooting an issue" -β†’ [RELEASE_QUICK_REFERENCE.md](./RELEASE_QUICK_REFERENCE.md) β†’ "Troubleshoot" - -### "I need to communicate a release to stakeholders" -β†’ [RELEASE_VISUAL_GUIDE.md](./RELEASE_VISUAL_GUIDE.md) β†’ "Status Page Template" - -### "I want to automate releases" -β†’ [RELEASE_WORKFLOW.md](./RELEASE_WORKFLOW.md) β†’ "Automation Scripts" - ---- - -## πŸ“š Document Overview - -### [RELEASE_STRATEGY.md](./RELEASE_STRATEGY.md) -**The Master Document** - -| Aspect | Details | -|--------|---------| -| **Purpose** | Canonical strategy reference | -| **Audience** | Technical leads, architects | -| **Length** | ~300 lines | -| **Read Time** | 15-20 min | -| **Key Topics** | Versioning, naming, cadence, dependency order, rollback | -| **Use When** | Making strategic decisions | - -**Sections:** -- Semantic Versioning strategy -- Tag naming convention -- Release cadence (dev/staging/prod) -- Product dependencies -- Release checklist -- Protected tags setup -- Rollback procedures - ---- - -### [RELEASE_WORKFLOW.md](./RELEASE_WORKFLOW.md) -**The Execution Guide** - -| Aspect | Details | -|--------|---------| -| **Purpose** | Step-by-step release instructions | -| **Audience** | Developers, release engineers | -| **Length** | ~400 lines | -| **Read Time** | 20-30 min (skim) / 60 min (full) | -| **Key Topics** | Quick start, multi-product, hotfix, git commands | -| **Use When** | Actually performing a release | - -**Sections:** -- Quick start (single product) -- Multi-product coordinated release -- Hotfix procedure with steps -- Git commands reference -- Useful scripts to create -- Release checklist template - ---- - -### [RELEASE_IMPLEMENTATION.md](./RELEASE_IMPLEMENTATION.md) -**The Setup Guide** - -| Aspect | Details | -|--------|---------| -| **Purpose** | First-time setup and implementation | -| **Audience** | DevOps, release engineering | -| **Length** | ~500 lines | -| **Read Time** | 30-45 min (planning) / 2-4 hours (execution) | -| **Key Topics** | Initial setup, GitHub config, CI/CD, team training | -| **Use When** | Setting up process for the first time | - -**Phases:** -1. Initial setup (create baseline tags) -2. GitHub configuration (branch protection) -3. CI/CD integration -4. Release documentation -5. Team training -6. First real release walkthrough - ---- - -### [RELEASE_VISUAL_GUIDE.md](./RELEASE_VISUAL_GUIDE.md) -**The Diagram Reference** - -| Aspect | Details | -|--------|---------| -| **Purpose** | Visual flows and process diagrams | -| **Audience** | Everyone (visual learners) | -| **Length** | ~400 lines | -| **Read Time** | 15-20 min | -| **Key Topics** | Pipelines, dependencies, timelines, templates | -| **Use When** | Understanding processes, presentations | - -**Diagrams:** -- Release pipeline overview -- Product dependency & order -- Git tag timeline -- Release branch structure -- Multi-product coordination -- Hotfix flow -- Version matrix dashboard - ---- - -### [RELEASE_QUICK_REFERENCE.md](./RELEASE_QUICK_REFERENCE.md) -**The One-Page Reference** - -| Aspect | Details | -|--------|---------| -| **Purpose** | Quick lookup while working | -| **Audience** | All team members | -| **Length** | ~200 lines | -| **Read Time** | 5 min (scan) | -| **Key Topics** | Commands, naming, checklist, steps | -| **Use When** | Quick lookup, print & pin to desk | - -**Includes:** -- ⚑ Quick commands -- 🏷️ Tag naming format -- πŸ“ Pre-tag checklist -- πŸš€ Quick release steps -- πŸ“ Version file locations -- πŸ”„ Release timeline table -- πŸ“ž Common tasks - -**πŸ’‘ Print this one!** - ---- - -### [VERSION_FILES_REFERENCE.md](./VERSION_FILES_REFERENCE.md) -**The File Locations Guide** - -| Aspect | Details | -|--------|---------| -| **Purpose** | Exact file locations and how to update | -| **Audience** | Developers doing version bumps | -| **Length** | ~350 lines | -| **Read Time** | 5-10 min per product | -| **Key Topics** | File paths, format, examples per product | -| **Use When** | Updating version numbers | - -**Per Product:** -- Staff Mobile App -- Client Mobile App -- Web Dashboard -- Command API Backend -- Core API Backend -- DataConnect Schema -- CHANGELOG.md - ---- - -### [RELEASE_PACKAGE_SUMMARY.md](./RELEASE_PACKAGE_SUMMARY.md) -**This Package Overview** - -| Aspect | Details | -|--------|---------| -| **Purpose** | Overview of all 6 documents | -| **Audience** | New team members, anyone | -| **Length** | ~400 lines | -| **Read Time** | 15 min | -| **Key Topics** | Package contents, usage paths, next steps | -| **Use When** | Understanding what documents exist | - -**Includes:** -- Complete package description -- How to use each document -- Current baseline versions -- Immediate next steps -- Feature checklist -- Success metrics - ---- - -## 🎯 Reading Paths by Role - -### Developer (Contributing Code) -1. skim: [RELEASE_STRATEGY.md](./RELEASE_STRATEGY.md) (5 min) -2. keep: [RELEASE_QUICK_REFERENCE.md](./RELEASE_QUICK_REFERENCE.md) at desk -3. when needed: [VERSION_FILES_REFERENCE.md](./VERSION_FILES_REFERENCE.md) - -### Release Engineer -1. read: [RELEASE_IMPLEMENTATION.md](./RELEASE_IMPLEMENTATION.md) (full) -2. master: [RELEASE_WORKFLOW.md](./RELEASE_WORKFLOW.md) (full) -3. reference: [RELEASE_STRATEGY.md](./RELEASE_STRATEGY.md) -4. check: [VERSION_FILES_REFERENCE.md](./VERSION_FILES_REFERENCE.md) - -### Technical Lead / Architect -1. read: [RELEASE_STRATEGY.md](./RELEASE_STRATEGY.md) (full) -2. review: [RELEASE_VISUAL_GUIDE.md](./RELEASE_VISUAL_GUIDE.md) -3. approve: [RELEASE_IMPLEMENTATION.md](./RELEASE_IMPLEMENTATION.md) -4. maintain: Update [RELEASE_PACKAGE_SUMMARY.md](./RELEASE_PACKAGE_SUMMARY.md) - -### Product Manager / Business Lead -1. understand: [RELEASE_STRATEGY.md](./RELEASE_STRATEGY.md) β†’ Release Cadence section -2. visualize: [RELEASE_VISUAL_GUIDE.md](./RELEASE_VISUAL_GUIDE.md) β†’ Status Page Template -3. track: Version matrix dashboard -4. share: Communicate timelines to users - -### New Team Member -1. start: [RELEASE_STRATEGY.md](./RELEASE_STRATEGY.md) (overview) -2. watch: Team walkthrough of [RELEASE_VISUAL_GUIDE.md](./RELEASE_VISUAL_GUIDE.md) -3. practice: Follow [RELEASE_WORKFLOW.md](./RELEASE_WORKFLOW.md) with mentor -4. reference: Keep [RELEASE_QUICK_REFERENCE.md](./RELEASE_QUICK_REFERENCE.md) handy - ---- - -## πŸ”— Quick Links - -| Need | Go To | -|------|-------| -| Version numbers for all products | [VERSION_FILES_REFERENCE.md](./VERSION_FILES_REFERENCE.md) | -| How to release a single product | [RELEASE_WORKFLOW.md](./RELEASE_WORKFLOW.md) β†’ Quick Start | -| Git commands | [RELEASE_QUICK_REFERENCE.md](./RELEASE_QUICK_REFERENCE.md) β†’ Quick Commands | -| Branch structure | [RELEASE_VISUAL_GUIDE.md](./RELEASE_VISUAL_GUIDE.md) β†’ Git Tag Timeline | -| Hotfix steps | [RELEASE_WORKFLOW.md](./RELEASE_WORKFLOW.md) β†’ Hotfix Release | -| Release checklist | [RELEASE_QUICK_REFERENCE.md](./RELEASE_QUICK_REFERENCE.md) β†’ Checklist | -| Automation scripts | [RELEASE_WORKFLOW.md](./RELEASE_WORKFLOW.md) β†’ Automation Scripts | -| Dependency order | [RELEASE_VISUAL_GUIDE.md](./RELEASE_VISUAL_GUIDE.md) β†’ Dependency Diagram | -| GitHub setup | [RELEASE_IMPLEMENTATION.md](./RELEASE_IMPLEMENTATION.md) β†’ Phase 2 | -| Team training | [RELEASE_IMPLEMENTATION.md](./RELEASE_IMPLEMENTATION.md) β†’ Phase 5 | -| Status communication | [RELEASE_VISUAL_GUIDE.md](./RELEASE_VISUAL_GUIDE.md) β†’ Status Page Template | - ---- - -## πŸ“… Implementation Timeline - -``` -Week 1 (2026-03-05) -β”œβ”€ Read: RELEASE_STRATEGY.md -β”œβ”€ Review: RELEASE_VISUAL_GUIDE.md -└─ Decide: Approve strategy with team - -Week 2 (2026-03-08) -β”œβ”€ Follow: RELEASE_IMPLEMENTATION.md Phase 1-2 -β”œβ”€ Create: Initial dev tags (v0.1.0) -└─ Configure: GitHub branch protection - -Week 3 (2026-03-15) -β”œβ”€ Plan: First staging release -β”œβ”€ Use: RELEASE_WORKFLOW.md -β”œβ”€ Reference: VERSION_FILES_REFERENCE.md -└─ Check: RELEASE_QUICK_REFERENCE.md - -Week 4 (2026-03-22) -β”œβ”€ Execute: First production release -β”œβ”€ Monitor: 24 hours post-release -└─ Document: Learnings in process - -Month 2+ -└─ Repeat: Establish release rhythm -``` - ---- - -## βœ… Before You Start - -Make sure you have: - -- [ ] Read at least 2 documents from your reading path -- [ ] Understood tag naming convention -- [ ] Know location of version files for your product -- [ ] Have git/GitHub access -- [ ] Know deployment procedure for your environment -- [ ] Know your team's approval process - ---- - -## πŸŽ“ Learning Path by Goal - -### "I want to perform a release in the next hour" -1. skim: [RELEASE_QUICK_REFERENCE.md](./RELEASE_QUICK_REFERENCE.md) (5 min) -2. reference: [VERSION_FILES_REFERENCE.md](./VERSION_FILES_REFERENCE.md) (2 min) -3. follow: [RELEASE_WORKFLOW.md](./RELEASE_WORKFLOW.md) β†’ your scenario (30 min) - -**Time: 40 minutes** - -### "I want to understand the full strategy" -1. read: [RELEASE_STRATEGY.md](./RELEASE_STRATEGY.md) (20 min) -2. visualize: [RELEASE_VISUAL_GUIDE.md](./RELEASE_VISUAL_GUIDE.md) (10 min) -3. deep dive: [RELEASE_IMPLEMENTATION.md](./RELEASE_IMPLEMENTATION.md) (30 min) -4. reference: [VERSION_FILES_REFERENCE.md](./VERSION_FILES_REFERENCE.md) (10 min) - -**Time: 70 minutes** - -### "I want to teach others" -1. prep: [RELEASE_STRATEGY.md](./RELEASE_STRATEGY.md) (20 min) -2. visuals: [RELEASE_VISUAL_GUIDE.md](./RELEASE_VISUAL_GUIDE.md) (10 min) -3. demo: [RELEASE_WORKFLOW.md](./RELEASE_WORKFLOW.md) β†’ Quick Start (30 min) -4. handout: [RELEASE_QUICK_REFERENCE.md](./RELEASE_QUICK_REFERENCE.md) - -**Time: 60 minutes prep + 30 min teaching** - ---- - -## πŸ“ž Where to Find Things - -| Question | Document | -|----------|----------| -| What's our versioning scheme? | RELEASE_STRATEGY.md | -| How do I name tags? | RELEASE_QUICK_REFERENCE.md | -| What files do I need to edit? | VERSION_FILES_REFERENCE.md | -| How do I release a product? | RELEASE_WORKFLOW.md | -| Where do I get started? | RELEASE_IMPLEMENTATION.md | -| Show me diagrams | RELEASE_VISUAL_GUIDE.md | -| Quick git commands | RELEASE_QUICK_REFERENCE.md | -| Deployment order? | RELEASE_VISUAL_GUIDE.md | -| Hotfix steps? | RELEASE_WORKFLOW.md | -| Team training? | RELEASE_IMPLEMENTATION.md | - ---- - -## 🎯 Success Criteria - -After reading appropriate docs, you should know: - -- βœ… What semantic versioning means -- βœ… How to name a git tag -- βœ… Which files control versions for each product -- βœ… The three environment levels (dev/staging/prod) -- βœ… The product deployment order -- βœ… Where to find version files -- βœ… How to execute a release -- βœ… What to do if something goes wrong -- βœ… How to communicate a release - ---- - -## πŸ’‘ Pro Tips - -1. **Bookmark** this index page -2. **Print** [RELEASE_QUICK_REFERENCE.md](./RELEASE_QUICK_REFERENCE.md) -3. **Share** [RELEASE_VISUAL_GUIDE.md](./RELEASE_VISUAL_GUIDE.md) in presentations -4. **Reference** [VERSION_FILES_REFERENCE.md](./VERSION_FILES_REFERENCE.md) every release -5. **Update** as your process evolves - ---- - -## πŸ“ž Questions? - -1. **How?** β†’ Look in [RELEASE_WORKFLOW.md](./RELEASE_WORKFLOW.md) -2. **What file?** β†’ Look in [VERSION_FILES_REFERENCE.md](./VERSION_FILES_REFERENCE.md) -3. **Git command?** β†’ Look in [RELEASE_QUICK_REFERENCE.md](./RELEASE_QUICK_REFERENCE.md) -4. **Strategy?** β†’ Look in [RELEASE_STRATEGY.md](./RELEASE_STRATEGY.md) -5. **Diagram?** β†’ Look in [RELEASE_VISUAL_GUIDE.md](./RELEASE_VISUAL_GUIDE.md) -6. **Can't find it?** β†’ Ask in #releases on Slack - ---- - -## πŸš€ Ready? - -Pick your path above and start reading. You've got this! - -**Questions? Ask in #releases** - ---- - -**Created**: 2026-03-05 -**Last Updated**: 2026-03-05 -**Version**: 1.0 diff --git a/RELEASE_PACKAGE_SUMMARY.md b/RELEASE_PACKAGE_SUMMARY.md deleted file mode 100644 index 5557874e..00000000 --- a/RELEASE_PACKAGE_SUMMARY.md +++ /dev/null @@ -1,507 +0,0 @@ -# Release Strategy - Complete Package Summary - -**Created**: 2026-03-05 -**Status**: Ready for Implementation -**Document Set**: Complete & Integrated - ---- - -## πŸ“š What Was Created - -A complete, production-ready release and tagging strategy for the KROW Workforce monorepo with 5 independent products. - -### Documents Included - -#### 1. **RELEASE_STRATEGY.md** πŸ“– -**Purpose**: The canonical strategy document -**Contents**: -- Semantic versioning approach (SemVer) -- Git tag naming convention -- Release cadence (dev/staging/prod) -- Deployment dependency order -- Release checklist -- Protected tag rules -- Version file locations -- Rollback procedures - -**Audience**: Technical leads, team members planning releases -**Length**: ~300 lines -**Use When**: Making strategic decisions about releases - ---- - -#### 2. **RELEASE_WORKFLOW.md** πŸ”§ -**Purpose**: Step-by-step execution guide -**Contents**: -- Quick start release (single product) -- Multi-product coordinated release -- Hotfix procedure -- Useful git commands -- Automation scripts to create -- Release checklist template - -**Audience**: Developers and release engineers executing releases -**Length**: ~400 lines -**Use When**: Actually performing a release - ---- - -#### 3. **RELEASE_IMPLEMENTATION.md** πŸš€ -**Purpose**: Setup and first-release guide -**Contents**: -- Phase 1: Initial setup (create baseline tags) -- Phase 2: GitHub configuration (branch protection) -- Phase 3: CI/CD integration -- Phase 4: Release documentation -- Phase 5: Team training -- Phase 6: First real release walkthrough -- Communication plan -- Troubleshooting - -**Audience**: DevOps/Release engineering team -**Length**: ~500 lines -**Use When**: Setting up the release process for the first time - ---- - -#### 4. **RELEASE_VISUAL_GUIDE.md** πŸ“Š -**Purpose**: ASCII diagrams and visual references -**Contents**: -- Release pipeline overview (flowchart) -- Product dependency diagram -- Git tag timeline example -- Release branch structure diagram -- Multi-product release coordination -- Hotfix flow diagram -- Version matrix dashboard template -- Release timeline template -- Status page template - -**Audience**: Everyone (visual learners, quick reference) -**Length**: ~400 lines -**Use When**: Understanding the flow, presentations, team communication - ---- - -#### 5. **RELEASE_QUICK_REFERENCE.md** 🎯 -**Purpose**: One-page quick reference (print-friendly) -**Contents**: -- Quick commands -- Tag naming format -- Pre-tag checklist -- Quick release steps -- Version file locations -- Release timeline table -- Common tasks with code examples -- Deployment order -- Red flags to avoid -- Troubleshooting - -**Audience**: All team members -**Length**: ~200 lines -**Use When**: Quick lookup while working - -**πŸ’‘ Tip**: Print this and pin to your desk! - ---- - -#### 6. **VERSION_FILES_REFERENCE.md** πŸ“ -**Purpose**: Exact file locations and update instructions -**Contents**: -- Staff Mobile pubspec.yaml location -- Client Mobile pubspec.yaml location -- Web Dashboard package.json location -- Command API package.json location -- Core API package.json location -- DataConnect schema version (if applicable) -- CHANGELOG.md (all products) -- Release checklist per product -- Version update template script -- Common mistakes -- Pro tips - -**Audience**: Developers doing version bumps -**Length**: ~350 lines -**Use When**: Updating version numbers for a release - ---- - -## 🎯 How to Use This Package - -### For Your First Release - -1. **Read** [RELEASE_STRATEGY.md](./RELEASE_STRATEGY.md) (strategic overview) -2. **Follow** [RELEASE_IMPLEMENTATION.md](./RELEASE_IMPLEMENTATION.md) (Phase 1-6 setup) -3. **Reference** [VERSION_FILES_REFERENCE.md](./VERSION_FILES_REFERENCE.md) (exact files to update) -4. **Execute** [RELEASE_WORKFLOW.md](./RELEASE_WORKFLOW.md) (step-by-step) -5. **Check** [RELEASE_VISUAL_GUIDE.md](./RELEASE_VISUAL_GUIDE.md) (understand the flow) -6. **Keep** [RELEASE_QUICK_REFERENCE.md](./RELEASE_QUICK_REFERENCE.md) handy - -### For Ongoing Releases - -**Quick path:** -1. [RELEASE_QUICK_REFERENCE.md](./RELEASE_QUICK_REFERENCE.md) - Commands & checklist -2. [VERSION_FILES_REFERENCE.md](./VERSION_FILES_REFERENCE.md) - Which files to update -3. [RELEASE_WORKFLOW.md](./RELEASE_WORKFLOW.md) - Copy the relevant section -4. [RELEASE_VISUAL_GUIDE.md](./RELEASE_VISUAL_GUIDE.md) - Verify deployment order - -### For Team Training - -1. **Share** [RELEASE_STRATEGY.md](./RELEASE_STRATEGY.md) with team -2. **Show** [RELEASE_VISUAL_GUIDE.md](./RELEASE_VISUAL_GUIDE.md) diagrams -3. **Walk through** [RELEASE_WORKFLOW.md](./RELEASE_WORKFLOW.md) quick start -4. **Provide** [RELEASE_QUICK_REFERENCE.md](./RELEASE_QUICK_REFERENCE.md) as handout -5. **Reference** [VERSION_FILES_REFERENCE.md](./VERSION_FILES_REFERENCE.md) when needed - -### For CI/CD Setup - -1. Review automation sections in [RELEASE_WORKFLOW.md](./RELEASE_WORKFLOW.md) -2. Set up GitHub branch protection per [RELEASE_IMPLEMENTATION.md](./RELEASE_IMPLEMENTATION.md) -3. Configure CodeMagic per [RELEASE_STRATEGY.md](./RELEASE_STRATEGY.md) - ---- - -## 🏷️ Quick Reference: Tag Naming - -``` -Format: /-v - -Staff Mobile Example: staff-mobile/prod-v1.0.0 -Client Mobile Example: client-mobile/prod-v1.0.0 -Web Dashboard Example: web-dashboard/staging-v0.1.0 -Command API Example: command-api/dev-v0.2.0 -Core API Example: core-api/prod-v0.1.0 - -Environments: - dev β†’ Development releases (daily/weekly) - staging β†’ Pre-production releases (bi-weekly) - prod β†’ Production releases (monthly) -``` - ---- - -## πŸ“Š Current Baseline Versions - -Based on your repository state (2026-03-05): - -| Product | Current Version | Status | -|---------|-----------------|--------| -| Staff Mobile | 0.1.0 | Development | -| Client Mobile | 0.1.0 | Development | -| Web Dashboard | 0.0.0 | Pre-release | -| Command API | 0.1.0 | Development | -| Core API | 0.1.0 | Development | - -**Next Releases**: -- Q1 2026: v0.2.0 (staging) -- Q2 2026: v1.0.0 (production) - ---- - -## πŸš€ Immediate Next Steps - -### This Week (2026-03-05) - -- [ ] Read [RELEASE_STRATEGY.md](./RELEASE_STRATEGY.md) -- [ ] Review with team -- [ ] Get approval to proceed - -### Next Week (2026-03-08) - -- [ ] Follow [RELEASE_IMPLEMENTATION.md](./RELEASE_IMPLEMENTATION.md) Phase 1-2 -- [ ] Create initial dev tags (baseline v0.1.0) -- [ ] Configure GitHub branch protection for prod tags -- [ ] Train team on new process - -### Week of Release (2026-03-15) - -- [ ] Plan first staging release (Staff Mobile v0.2.0) -- [ ] Update version all files per [VERSION_FILES_REFERENCE.md](./VERSION_FILES_REFERENCE.md) -- [ ] Execute release using [RELEASE_WORKFLOW.md](./RELEASE_WORKFLOW.md) -- [ ] Deploy to staging and test - -### Within 30 Days - -- [ ] First production release (any product) -- [ ] Establish release cadence -- [ ] Document any customizations -- [ ] Refine process based on learnings - ---- - -## βœ… Feature Checklist - -This release strategy includes: - -- βœ… **Semantic Versioning (SemVer)** - Industry standard -- βœ… **Product-specific Tags** - Independent version tracking -- βœ… **Environment Separation** - dev/staging/prod releases -- βœ… **Dependency Management** - Clear deployment order -- βœ… **Rollback Procedures** - Handling production issues -- βœ… **Hotfix Process** - Emergency fixes -- βœ… **Branch Protection** - GitHub security rules -- βœ… **Documentation** - Comprehensive guides -- βœ… **Templates** - Checklists and scripts -- βœ… **Visual Diagrams** - Process flows -- βœ… **Quick Reference** - Print-friendly guide -- βœ… **Version File Map** - Exact file locations -- βœ… **Communication Plan** - Stakeholder updates -- βœ… **Team Training** - Learning materials -- βœ… **Automation Scripts** - CI/CD integration - ---- - -## πŸ“‹ File Structure - -``` -Repository Root -β”œβ”€β”€ RELEASE_STRATEGY.md ← Strategic overview -β”œβ”€β”€ RELEASE_WORKFLOW.md ← Step-by-step execution -β”œβ”€β”€ RELEASE_IMPLEMENTATION.md ← Setup guide -β”œβ”€β”€ RELEASE_VISUAL_GUIDE.md ← Diagrams & flows -β”œβ”€β”€ RELEASE_QUICK_REFERENCE.md ← One-page reference -β”œβ”€β”€ VERSION_FILES_REFERENCE.md ← File locations -β”‚ -β”œβ”€β”€ CHANGELOG.md ← Version history (existing) -β”œβ”€β”€ codemagic.yaml ← CI/CD config (existing) -β”‚ -└── apps/ - β”œβ”€β”€ mobile/ - β”‚ β”œβ”€β”€ apps/ - β”‚ β”‚ β”œβ”€β”€ staff_app/pubspec.yaml ← Staff Mobile version - β”‚ β”‚ └── client_app/pubspec.yaml ← Client Mobile version - β”‚ └── ... - β”‚ - └── web/ - └── package.json ← Web Dashboard version - -backend/ -β”œβ”€β”€ command-api/package.json ← Command API version -└── core-api/package.json ← Core API version -``` - ---- - -## πŸ” Security & Best Practices - -### Branch Protection -- Production tags (`prod-v*`) require pull request review -- Require status checks to pass -- Require branches up-to-date -- Prevent force pushes - -### Rollback Safety -- Always keep previous version available -- Test rollback procedure regularly -- Document rollback steps -- Communicate with users - -### Change Tracking -- CHANGELOG.md for all product updates -- Git history for code changes -- Tags for release checkpoints -- GitHub Releases for user communication - ---- - -## πŸ’‘ Tips for Success - -### 1. Start Small -Begin with a single product release (e.g., Staff Mobile v0.2.0) to practice the process. - -### 2. Establish Rhythm -Consistent release cadence makes it easier for everyone: -- Dev: Weekly -- Staging: Bi-weekly -- Prod: Monthly - -### 3. Automate Wisely -Start manual to understand the process, then automate repetitive tasks. - -### 4. Communicate Early -Announce release plans before deployment, not after. - -### 5. Monitor Actively -24-hour post-release monitoring catches issues early. - -### 6. Document Learnings -Update these guides based on real experience with your releases. - ---- - -## πŸ› Troubleshooting - -### I'm confused about which file to edit -β†’ See [VERSION_FILES_REFERENCE.md](./VERSION_FILES_REFERENCE.md) - -### I need step-by-step release instructions -β†’ See [RELEASE_WORKFLOW.md](./RELEASE_WORKFLOW.md) - -### I need git commands -β†’ See [RELEASE_QUICK_REFERENCE.md](./RELEASE_QUICK_REFERENCE.md) - -### I need to understand the overall strategy -β†’ See [RELEASE_STRATEGY.md](./RELEASE_STRATEGY.md) - -### I need to set up the process for the first time -β†’ See [RELEASE_IMPLEMENTATION.md](./RELEASE_IMPLEMENTATION.md) - -### I need visual diagrams -β†’ See [RELEASE_VISUAL_GUIDE.md](./RELEASE_VISUAL_GUIDE.md) - ---- - -## πŸ“ž Additional Resources - -### Related Documentation -- [CHANGELOG.md](./CHANGELOG.md) - Current version history -- [codemagic.yaml](./codemagic.yaml) - CI/CD configuration -- [docs/ARCHITECTURE/system-bible.md](./docs/ARCHITECTURE/system-bible.md) - System design -- [README.md](./README.md) - Project overview - -### External References -- [Semantic Versioning 2.0.0](https://semver.org) -- [Git Tagging](https://git-scm.com/docs/git-tag) -- [GitHub Releases](https://docs.github.com/en/repositories/releasing-projects-on-github) -- [Git Workflow Best Practices](https://git-scm.com/book/en/v2) - ---- - -## πŸ‘₯ Team Roles - -### Release Manager -- Plans release schedule -- Creates tags -- Coordinates deployment -- Monitors post-release - -### Developers -- Ensure code is release-ready -- Update version files per checklist -- Update CHANGELOG -- Test releases - -### DevOps/Infrastructure -- Configure branch protection -- Set up CI/CD automations -- Deploy to environments -- Monitor infrastructure - -### Product Owner -- Approves staging releases -- Signs off before production -- Communicates with users -- Handles rollback decisions - -### QA Team -- Tests staged releases -- Verifies production deployments -- Reports issues -- Validates rollbacks - ---- - -## πŸ“Š Success Metrics - -Track these metrics for each release: - -- **Lead Time**: Time from commit to production -- **Deployment Frequency**: How often you release -- **Change Failure Rate**: % of releases needing rollback -- **Mean Time to Recovery**: Time to fix issues -- **Automation Coverage**: % of tasks automated -- **User Adoption**: % of users on latest version -- **Issue Detection**: Time from deployment to issue detection - ---- - -## πŸŽ“ Knowledge Sharing - -### For New Team Members -1. Have them read [RELEASE_STRATEGY.md](./RELEASE_STRATEGY.md) -2. Run through [RELEASE_WORKFLOW.md](./RELEASE_WORKFLOW.md) together -3. Have them perform a dev release under supervision -4. Give them [RELEASE_QUICK_REFERENCE.md](./RELEASE_QUICK_REFERENCE.md) as reference - -### For Leadership -Share [RELEASE_VISUAL_GUIDE.md](./RELEASE_VISUAL_GUIDE.md) status page template to track releases across products. - -### For Stakeholders -Use templates provided to communicate: -- Release announcements -- Feature summaries -- Deployment windows -- Known issues - ---- - -## πŸ“… Release Calendar Template - -``` -March 2026 -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ 01 (Sun) Code Freeze β”‚ -β”‚ 05 (Thu) Staging Release (0.2.0) β”‚ -β”‚ 08 (Sun) QA Complete β”‚ -β”‚ 15 (Sun) Production Release β”‚ -β”‚ 22 (Sun) Monitoring & Stability β”‚ -β”‚ 29 (Sun) Next Cycle Begins β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - -Every Monday: Release Sync Meeting -Every Friday: Status Update -Rolling: Release documentation updates -``` - ---- - -## ✨ Next Phase - -Once this strategy is implemented and proven with 2-3 releases: - -1. **Automation**: GitHub Actions to auto-tag on version change -2. **Metrics**: Dashboard tracking deployment metrics -3. **Communication**: Slack/email bot announcing releases -4. **Deployment**: Fully automated deployments per product -5. **Analytics**: Track adoption and issue post-release - ---- - -## πŸ“ Document Maintenance - -**When to update these guides:** -- After every major release (capture learnings) -- When process changes -- When team feedback warrants updates -- When new tools are integrated -- When scaling to new products - -**Who maintains:** -- DevOps/Release engineering team -- Approved by: Technical leads, Product management - -**Review Cycle:** -- Quarterly review of all documents -- Monthly: CHANGELOG.md updates -- As-needed: Bug fixes, clarifications - ---- - -## πŸŽ‰ You're Ready! - -This complete release strategy is ready to implement. Start with [RELEASE_IMPLEMENTATION.md](./RELEASE_IMPLEMENTATION.md) and follow the phases. - -**Questions?** -- Review the relevant guide above -- Consult [RELEASE_QUICK_REFERENCE.md](./RELEASE_QUICK_REFERENCE.md) -- Ask your DevOps team - -**Let's ship v1.0.0! πŸš€** - ---- - -**Package Version**: 1.0 -**Created**: 2026-03-05 -**Last Updated**: 2026-03-05 -**Status**: Ready for Production -**Maintainer**: DevOps/Release Engineering Team diff --git a/RELEASE_QUICK_REFERENCE.md b/RELEASE_QUICK_REFERENCE.md deleted file mode 100644 index b1dfbe88..00000000 --- a/RELEASE_QUICK_REFERENCE.md +++ /dev/null @@ -1,267 +0,0 @@ -# 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 - -``` -/-v.. - -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! πŸ”–** diff --git a/RELEASE_STRATEGY.md b/RELEASE_STRATEGY.md deleted file mode 100644 index a220e8db..00000000 --- a/RELEASE_STRATEGY.md +++ /dev/null @@ -1,425 +0,0 @@ -# KROW Workforce Release Strategy & Tagging Plan - -## πŸ“‹ Overview - -This document establishes a systematic approach to versioning, tagging, and releasing across the KROW Workforce monorepo, which contains 5 distinct products with interdependencies. - -**Products:** -1. **Staff Mobile App** - Flutter (iOS/Android) -2. **Client Mobile App** - Flutter (iOS/Android) -3. **Web Dashboard** - React/Vite -4. **Backend Services** - Node.js (Command API, Core API) -5. **Database/DataConnect** - Firebase Data Connect with PostgreSQL - ---- - -## πŸ”— Versioning Strategy - -### Semantic Versioning (SemVer) - -All products follow **Semantic Versioning 2.0.0**: -- **MAJOR.MINOR.PATCH** (e.g., `1.2.3`) -- **MAJOR**: Breaking changes, major features -- **MINOR**: Backward-compatible new features -- **PATCH**: Bug fixes, minor improvements - -### Version Independence - -Each product maintains its own version: -- Products can release independently -- No requirement for synchronized versions across products -- Allows flexibility in release schedules - -### Current Baseline (as of 2026-03-05) - -| Product | Current Version | Status | -|---------|-----------------|--------| -| Staff Mobile App | 0.1.0 | Development | -| Client Mobile App | 0.1.0 | Development | -| Web Dashboard | 0.0.0 | Pre-release | -| Backend (Command API) | 0.1.0 | Development | -| Backend (Core API) | 0.1.0 | Development | -| DataConnect | N/A | Schema-driven | - ---- - -## 🏷️ Git Tag Naming Convention - -### Format - -``` -/-v -``` - -### Products -- `staff-mobile` - Staff mobile application -- `client-mobile` - Client mobile application -- `web-dashboard` - Web dashboard -- `command-api` - Backend command API -- `core-api` - Backend core API -- `dataconnect` - Database/DataConnect schema - -### Environments -- `dev` - Development release (unstable, for testing) -- `staging` - Staging release (pre-production) -- `prod` - Production release (stable, customer-facing) - -### Examples -``` -staff-mobile/dev-v0.1.0 -client-mobile/staging-v0.1.0 -web-dashboard/prod-v1.0.0 -command-api/dev-v0.2.1 -dataconnect/prod-v0.3.0 -``` - -### Release Candidate Suffix (Optional) -For pre-release versions: -``` -staff-mobile/staging-v0.1.0-rc.1 -web-dashboard/prod-v1.0.0-rc.2 -``` - ---- - -## πŸ“… Release Cadence - -### Development Releases (`dev`) -- **Frequency**: Weekly or as-needed -- **Trigger**: Completed feature branches, bug fixes -- **Duration**: Not stable, for internal testing -- **Deployment**: Dev environment only - -### Staging Releases (`staging`) -- **Frequency**: Bi-weekly -- **Trigger**: Completion of sprint/feature milestone -- **Duration**: Should maintain stability for 1-2 weeks -- **Deployment**: Staging environment for QA - -### Production Releases (`prod`) -- **Frequency**: Monthly or sprint-based (typically end of month) -- **Trigger**: Successful staging validation + product sign-off -- **Duration**: Maintain for 2+ months -- **Deployment**: Production environment for customers - ---- - -## πŸ”„ Release Dependency Order - -### Critical Path (Recommended) - -**For synchronized releases:** - -1. **DataConnect Schema** (if schema changes) - Deploy first -2. **Backend Services** (Command API β†’ Core API) -3. **Web Dashboard** -4. **Mobile Apps** (Staff first, then Client) - -**Rationale:** -- DataConnect schema changes must be deployed before APIs consume new fields -- Backend APIs must be stable before frontend depends on new endpoints -- Web can be deployed independently but should test against new backend -- Mobile apps can be released independently but won't have full features until matching backend is live - -### Independent Releases - -Products can release independently if they don't introduce breaking changes: -- Mobile apps can release without backend changes -- Web dashboard can release bug fixes independently -- Backend can release non-breaking API changes independently - ---- - -## πŸ“¦ Release Checklist - -### Pre-Release (48 hours before) - -- [ ] Code review complete on all changes -- [ ] All tests passing (unit, integration, E2E) -- [ ] Mobile app builds succeed on CodeMagic -- [ ] No lint/type errors -- [ ] Performance benchmarks acceptable -- [ ] Security scan completed -- [ ] Documentation updated -- [ ] CHANGELOG.md updated with changes - -### Release Day - -- [ ] Create release branch from main: `release/v` -- [ ] Update version numbers in all relevant files: - - Mobile: `pubspec.yaml` version + build number - - Web: `package.json` version - - Backend: `package.json` version - - Backend: Update `codemagic.yaml` version refs -- [ ] Create git tag with appropriate name -- [ ] Merge release branch back to main -- [ ] Deploy to target environment -- [ ] Smoke tests run successfully -- [ ] Create GitHub Release with: - - Release notes from CHANGELOG - - Build artifacts (APK/AAB for mobile) - - Deployment checklist items - - Known issues - -### Post-Release - -- [ ] Verify in target environment (staging β†’ prod) -- [ ] Monitor error logs for 24 hours -- [ ] Notify users of deployment -- [ ] Update status page if applicable -- [ ] Tag next development version as beginning - ---- - -## πŸ” Protected Tags - -### Rules - -- **Production tags (`prod-v*`)**: Require pull request review -- **Staging tags (`staging-v*`)**: Require at least 1 approval -- **Dev tags (`dev-v*`)**: No restrictions - -### Implementation in GitHub - -1. Go to Repo Settings β†’ Branches β†’ Add rule -2. Apply to tag name pattern: `**/prod-v*` -3. Require pull request reviews before merging -4. Require status checks to pass - ---- - -## πŸ“ Version File Locations - -### Mobile Apps (Staff & Client) - -**File**: `/apps/mobile/apps/staff_app/pubspec.yaml` (and client_app) -```yaml -version: 0.1.0+1 -``` -- First number = version -- After `+` = build number (increment for each release) - -### Web Dashboard - -**File**: `/apps/web/package.json` -```json -{ - "version": "0.0.0" -} -``` - -### Backend Services - -**Files**: -- `/backend/command-api/package.json` -- `/backend/core-api/package.json` - -```json -{ - "version": "0.1.0" -} -``` - -### CodeMagic Configuration - -**File**: `/codemagic.yaml` -```yaml -workflows: - mobile-client-build: - environment: - flutter: stable - settings: - build_version: "0.1.0" # Update this -``` - ---- - -## πŸ“Š Release Timeline Example: v1.0.0 - -**Timeline for coordinated production release:** - -``` -Day 1 (Monday) -β”œβ”€ Code freeze announced -β”œβ”€ All feature branches merged to main -└─ QA begins testing - -Day 6 (Saturday) -β”œβ”€ All tests pass -β”œβ”€ Release manager creates release/v1.0.0 branch -└─ Version numbers bumped to 1.0.0 everywhere - -Day 7 (Sunday) -β”œβ”€ Tags created: -β”‚ β”œβ”€ web-dashboard/staging-v1.0.0 -β”‚ β”œβ”€ command-api/staging-v1.0.0 -β”‚ β”œβ”€ core-api/staging-v1.0.0 -β”‚ β”œβ”€ staff-mobile/staging-v1.0.0 -β”‚ β”œβ”€ client-mobile/staging-v1.0.0 -β”‚ └─ dataconnect/staging-v1.0.0 (if schema changes) -β”œβ”€ Deploy to staging environment -β”œβ”€ QA smoke tests -└─ Product owner sign-off - -Day 13 (Saturday) - Production Release -β”œβ”€ Create production tags: -β”‚ β”œβ”€ web-dashboard/prod-v1.0.0 -β”‚ β”œβ”€ command-api/prod-v1.0.0 -β”‚ └─ [other products] -β”œβ”€ Deploy to production (following dependency order) -β”œβ”€ Verify in production -└─ Release GitHub Release page -``` - ---- - -## πŸ› οΈ Git Commands - -### Create a Tag - -```bash -# Create annotated tag -git tag -a staff-mobile/dev-v0.1.0 -m "Staff mobile v0.1.0 - [feature description]" - -# Push tag to remote -git push origin staff-mobile/dev-v0.1.0 - -# Or push all tags -git push origin --tags -``` - -### List Tags for a Product - -```bash -# Show all staff-mobile tags -git tag -l "staff-mobile/*" --sort=-version:refname - -# Show tags in specific environment -git tag -l "*/prod-v*" -``` - -### Delete a Tag - -```bash -# Local deletion -git tag -d staff-mobile/dev-v0.1.0 - -# Remote deletion -git push origin --delete staff-mobile/dev-v0.1.0 -``` - ---- - -## πŸ” Rollback Procedures - -### If Critical Issue Found in Prod - -1. **Identify**: Determine which product caused the issue -2. **Revert**: - ```bash - git revert -m 1 - git push origin main - ``` -3. **Tag**: Create hotfix tag - ```bash - git tag -a staff-mobile/prod-v0.1.1 -m "Hotfix: [issue description]" - git push origin staff-mobile/prod-v0.1.1 - ``` -4. **Deploy**: Follow deployment checklist -5. **Communication**: Notify users and stakeholders - -### If Staging Issue Found - -Similar to rollback but to staging environment. No customer impact. - ---- - -## πŸ“‹ Release Notes Template - -Create a GitHub Release with the following: - -```markdown -# Staff Mobile v0.1.0 Release - -**Release Date**: 2026-03-15 - -## What's New - -### Features -- [ ] Feature 1 description -- [ ] Feature 2 description - -### Improvements -- [ ] Improvement 1 description - -### Bug Fixes -- [ ] Bug fix 1 description - -## Dependencies - -- βœ… Requires Backend API v0.1.0 or higher -- βœ… Requires DataConnect schema v0.3.0 or higher - -## Installation - -[iOS/Android download links] - -## Known Issues - -- [ ] Issue 1: Description (Workaround: ...) - -## Migration Guide (if needed) - -Steps for users to migrate from previous version. - -## Support - -For issues, contact support@krow-workforce.com or [GitHub Issues Link] -``` - ---- - -## πŸ“Š Monitoring & Metrics - -### Track Per Release - -- [ ] Time to release -- [ ] Number of bugs in production -- [ ] User adoption rate -- [ ] Performance changes -- [ ] Rollback rate -- [ ] Deploy success rate - -### Dashboard - -Consider setting up a tool to track: -- Deploy frequency -- Lead time for changes -- Mean time to recovery (MTTR) -- Change failure rate - ---- - -## πŸ”— Related Documents - -- [CHANGELOG.md](./CHANGELOG.md) - Historical version logs -- [docs/01-backend-api-specification.md](./docs/01-backend-api-specification.md) - API contract -- [docs/ARCHITECTURE/system-bible.md](./docs/ARCHITECTURE/system-bible.md) - System design -- [codemagic.yaml](./codemagic.yaml) - CI/CD pipeline - ---- - -## βœ… Next Steps - -1. **Approve this strategy** with the team -2. **Configure GitHub branch protection** for tag patterns -3. **Set up release automation** in CI/CD (GitHub Actions or CodeMagic) -4. **Create the v1.0.0 milestone** with all planned features -5. **Establish communication cadence** for releases (weekly status, release announcements) -6. **Train team members** on release process - ---- - -**Last Updated**: 2026-03-05 -**Owner**: DevOps/Release Engineering -**Status**: βœ… Active diff --git a/RELEASE_VISUAL_GUIDE.md b/RELEASE_VISUAL_GUIDE.md deleted file mode 100644 index f7646d11..00000000 --- a/RELEASE_VISUAL_GUIDE.md +++ /dev/null @@ -1,382 +0,0 @@ -# Release Process Visual Guide - -## πŸ”„ Release Pipeline Overview - -``` -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ KROW WORKFORCE RELEASE PIPELINE β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - -β”Œβ”€ DEVELOPMENT PHASE ────────────────────────────────────────────┐ -β”‚ β”‚ -β”‚ Feature Branch Development β”‚ -β”‚ ↓ β”‚ -β”‚ Code Review & Testing β”‚ -β”‚ ↓ β”‚ -β”‚ Merge to Main β”‚ -β”‚ ↓ β”‚ -β”‚ Automated Builds & Tests (GitHub Actions / CodeMagic) β”‚ -β”‚ ↓ β”‚ -β”‚ βœ… Main is always deployment-ready β”‚ -β”‚ β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - ↓ -β”Œβ”€ STAGING RELEASE ──────────────────────────────────────────────┐ -β”‚ β”‚ -β”‚ 1. Create Release Branch (release/[product]-v[version]) β”‚ -β”‚ 2. Bump Version Numbers β”‚ -β”‚ 3. Update CHANGELOG β”‚ -β”‚ 4. Create Git Tags: */staging-v[version] β”‚ -β”‚ 5. Deploy to Staging Environment β”‚ -β”‚ 6. Run QA Tests β”‚ -β”‚ 7. Product Owner Sign-off β”‚ -β”‚ β”‚ -β”‚ Duration: 1 week minimum β”‚ -β”‚ Cadence: Bi-weekly β”‚ -β”‚ β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - ↓ - β”Œβ”€ ISSUE? ──────────────────┐ - β”‚ ↓ - β”‚ Create Hotfix - β”‚ Branch/Tag - β”‚ (*/staging-v[X+1]) - └─ FIX & RETEST β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - ↓ -β”Œβ”€ PRODUCTION RELEASE ───────────────────────────────────────────┐ -β”‚ β”‚ -β”‚ 1. Final Verification in Staging β”‚ -β”‚ 2. Create Production Tags: */prod-v[version] β”‚ -β”‚ 3. Deploy in Dependency Order: β”‚ -β”‚ β€’ DataConnect Schema (if applicable) β”‚ -β”‚ β€’ Command API β”‚ -β”‚ β€’ Core API β”‚ -β”‚ β€’ Web Dashboard β”‚ -β”‚ β€’ Staff Mobile β”‚ -β”‚ β€’ Client Mobile β”‚ -β”‚ 4. Smoke Tests in Production β”‚ -β”‚ 5. Create GitHub Release Page β”‚ -β”‚ 6. Announce to Users β”‚ -β”‚ 7. Monitor for 24 hours β”‚ -β”‚ β”‚ -β”‚ Duration: 1-2 hours deployment, 24-48 hours monitoring β”‚ -β”‚ Cadence: Monthly or sprint-based β”‚ -β”‚ β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - -Legend: - βœ… = Ready state - β†’ = Next step - ↓ = Dependency -``` - ---- - -## πŸ“¦ Product Dependency & Release Order - -``` - β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” - β”‚ DataConnect Schema β”‚ - β”‚ (if applicable) β”‚ - β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - β”‚ - β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” - β”‚ Backend Services β”‚ - β”‚ β”‚ - β”œβ”€ Command API β”‚ - └─ Core API β”‚ - β”‚ - β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” - β”‚ β”‚ β”‚ - β”Œβ”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β–Όβ”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β–Όβ”€β”€β”€β”€β”€β”€β” - β”‚ Web β”‚ β”‚ Staff β”‚ β”‚ Client β”‚ - β”‚ Dashboard β”‚ β”‚ Mobile β”‚ β”‚ Mobile β”‚ - β”‚ β”‚ β”‚ App β”‚ β”‚ App β”‚ - β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - -Critical Path (Staging β†’ Production): - 1. DataConnect (if schema changes) - 2. APIs (Command + Core) [parallel OK] - 3. Web Dashboard [can wait for API confirmation] - 4. Mobile Apps [independent, can deploy anytime] - -Parallel Deployments (when safe): - β€’ Both backend APIs can deploy in parallel - β€’ Mobile apps can deploy in parallel - β€’ Web + Mobile can deploy in parallel (if APIs stable) - -Non-Blocking: - β€’ Mobile can release without web changes - β€’ Web can release without mobile changes - β€’ Backend can release non-breaking API changes independently -``` - ---- - -## 🏷️ Git Tag Timeline Example - -``` - Release v1.0.0 Timeline (Coordinated) - -2026-03-01 2026-03-08 2026-03-15 2026-03-22 -β”‚ β”‚ β”‚ β”‚ -β”œβ”€ Code Freeze β”œβ”€ Staging Release β”œβ”€ Production β”œβ”€ Next Sprint -β”‚ β”‚ β”‚ Release β”‚ -β”œβ”€ Feature Branches β”œβ”€ */staging-v1.0.0 β”œβ”€ */prod-v1.0.0 β”‚ -β”‚ β†’ main β”‚ β”‚ β”‚ -β”‚ β”œβ”€ QA Testing β”œβ”€ Deploy & Verify β”‚ -β”œβ”€ All Tests # β”œβ”€ 24h Monitoring β”œβ”€ 48h Monitoring β”‚ -β”‚ Green # β”‚ β”‚ β”‚ -β”‚ β”œβ”€ Product Sign-off βœ“ β”œβ”€ Users Notified β”‚ -└─ Ready βœ“ └─ Approved for Prod └─ Stable βœ“ β”‚ - -Key Milestones: - # = All automated tests passing - βœ“ = Manual approval/sign-off -``` - ---- - -## πŸ”„ Release Branch Structure - -``` -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ main (Protected) ──────────────────┐ -β”‚ β”‚ -β”‚ feature/auth feature/payments β”‚ -β”‚ ↓ ↓ β”‚ -β”‚ ──●──●──●── ──●──●──●── ──●──●──●── ← Feature β”‚ -β”‚ β”‚ β”‚ β”‚ Branches β”‚ -β”‚ β”œβ”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€ ┬─────── β”‚ -β”‚ ↓ β”‚ ↓ β”‚ ↓ β”‚ -β”‚ ────●──────●─────●─────●──────●───── ← Merge PRs β”‚ -β”‚ β”‚ β”‚ -β”‚ ↓ β”‚ -β”‚ release/staff-mobile-v0.2.0 ← Release Branch β”‚ -β”‚ β”‚ β”‚ -β”‚ β”œβ”€ Bump version β”‚ -β”‚ β”œβ”€ Update CHANGELOG β”‚ -β”‚ β”œβ”€ Commit & merge back β”‚ -β”‚ β”‚ β”‚ -β”‚ ────●●────────────────── ← Merge back to main β”‚ -β”‚ β”‚ β”‚ -β”‚ ↓ β”‚ -β”‚ TAG: staff-mobile/staging-v0.2.0 ← Staging Tag β”‚ -β”‚ TAG: staff-mobile/prod-v0.2.0 ← Prod Tag β”‚ -β”‚ β”‚ β”‚ -β”‚ (Deploy from tags) β”‚ -β”‚ β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - -Key Points: - β€’ main is always clean and deployable - β€’ Feature branches never go to staging/prod - β€’ Tags point to main (after merge) - β€’ Releases == Git tags, not branches - β€’ Hotfix branches created from prod tags -``` - ---- - -## πŸ“‹ Multi-Product Release Coordination - -``` -Product Release States (Example: v1.0.0) - -Staff Mobile: - β”œβ”€ Dev build: βœ… staff-mobile/dev-v1.0.0 (deployed) - β”œβ”€ Staging: βœ… staff-mobile/staging-v1.0.0 (testing) - └─ Production: πŸ”„ staff-mobile/prod-v1.0.0 (deploying) - -Client Mobile: - β”œβ”€ Dev build: βœ… client-mobile/dev-v1.0.0 (deployed) - β”œβ”€ Staging: βœ… client-mobile/staging-v1.0.0 (testing) - └─ Production: πŸ”„ client-mobile/prod-v1.0.0 (deploying) - -Web Dashboard: - β”œβ”€ Dev build: βœ… web-dashboard/dev-v1.0.0 (deployed) - β”œβ”€ Staging: βœ… web-dashboard/staging-v1.0.0 (testing) - └─ Production: βœ… web-dashboard/prod-v1.0.0 (live) - -Command API: - β”œβ”€ Dev build: βœ… command-api/dev-v1.0.0 (deployed) - β”œβ”€ Staging: βœ… command-api/staging-v1.0.0 (testing) - └─ Production: βœ… command-api/prod-v1.0.0 (live) - -Core API: - β”œβ”€ Dev build: βœ… core-api/dev-v1.0.0 (deployed) - β”œβ”€ Staging: βœ… core-api/staging-v1.0.0 (testing) - └─ Production: βœ… core-api/prod-v1.0.0 (live) - -Legend: - βœ… = Released and stable - πŸ”„ = In progress - ⏳ = Waiting for approval - β›” = Blocked/awaiting fix - - -Sync Points (when to coordinate): - 1. Before moving staging β†’ prod (all ready?) - 2. During prod deployment (follow order) - 3. Post-release (all working?) - 4. If hotfix needed (which products affected?) -``` - ---- - -## 🚨 Hotfix Release Flow - -``` -Production Issue Detected - β”‚ - ↓ - β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” - β”‚ Is it critical? β”‚ - β””β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”˜ - β”‚ YES β”‚ NO - ↓ └─→ Plan for next release - - β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” - β”‚ Create Hotfix Branch β”‚ - β”‚ (from prod tag) β”‚ - β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - β”‚ - ↓ - β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” - β”‚ Make Fix β”‚ - β”‚ Test locally β”‚ - β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - β”‚ - ↓ - β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” - β”œβ”€ Bump PATCH version β”‚ - β”‚ (e.g., 0.1.0 β†’ 0.1.1) β”‚ - β”œβ”€ Update CHANGELOG β”‚ - β”œβ”€ Commit to hotfix branchβ”‚ - β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - β”‚ - ↓ - β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” - β”‚ Code Review (expedited) β”‚ - β”‚ Approval + merge β”‚ - β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - β”‚ - ↓ - β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” - β”‚ Create Tag β”‚ - β”‚ */prod-v0.1.1 β”‚ - β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - β”‚ - ↓ - β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” - β”‚ Deploy to Production β”‚ - β”‚ (High priority) β”‚ - β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - β”‚ - ↓ - β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” - β”‚ Verify Fix β”‚ - β”‚ Monitor 24h β”‚ - β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - β”‚ - ↓ - β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” - β”‚ Communicate to Users β”‚ - β”‚ Incident Report β”‚ - β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - β”‚ - ↓ - βœ… Resolved - -Speed target: 4-8 hours total (from detection to production verification) -``` - ---- - -## πŸ“Š Version Matrix Dashboard - -Create in your team wiki/notion: - -``` -╔════════════════════════════════╦═══════════╦═══════════╦═══════════╗ -β•‘ Product β•‘ Dev β•‘ Staging β•‘ Prod β•‘ -╠════════════════════════════════╬═══════════╬═══════════╬═══════════╣ -β•‘ Staff Mobile β•‘ 0.2.1 β•‘ 0.2.0 β•‘ 0.1.0 β•‘ -β•‘ Client Mobile β•‘ 0.2.1 β•‘ 0.2.0 β•‘ 0.1.0 β•‘ -β•‘ Web Dashboard β•‘ 0.1.0 β•‘ 0.0.0 β•‘ β€” β•‘ -β•‘ Command API β•‘ 0.2.0 β•‘ 0.2.0-rc1 β•‘ 0.1.0 β•‘ -β•‘ Core API β•‘ 0.2.0 β•‘ 0.2.0-rc1 β•‘ 0.1.0 β•‘ -β•‘ DataConnect β•‘ 0.4.0 β•‘ 0.3.0 β•‘ 0.3.0 β•‘ -β•šβ•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•β•©β•β•β•β•β•β•β•β•β•β•β•β•©β•β•β•β•β•β•β•β•β•β•β•β•©β•β•β•β•β•β•β•β•β•β•β•β• - -Last updated: 2026-03-05 -Updated by: DevOps Team -Next release planning: 2026-03-08 -``` - ---- - -## ⏱️ Release Timeline Template - -For every release, create this timeline: - -``` -Release: [Product] v[Version] -Target: [date] - -Milestones: -β”œβ”€ Feb 28 (T-7): Code freeze -β”œβ”€ Mar 1 (T-6): Staging release + QA testing -β”œβ”€ Mar 5 (T-2): Final staging verification -β”œβ”€ Mar 6 (T-1): Production deployment readiness -β”œβ”€ Mar 7 (T-0): Production deployment 14:00-16:00 UTC -β”œβ”€ Mar 8 (T+1): Monitoring & verification -└─ Mar 9 (T+2): Release celebration πŸŽ‰ - -Deployment Windows: - Testing: Anytime - Staging: Anytime - Prod: 14:00-16:00 UTC on release day - (Off-peak time in all timezones) - -Rollback Window: 4 hours post-deployment -``` - ---- - -## 🎯 Status Page Template - -Share with stakeholders: - -``` -πŸš€ KROW Workforce Release Status - -πŸ“… Week of March 5, 2026 - -Current Production Versions: -β”œβ”€β”€ Staff Mobile: 0.1.0 βœ… -β”œβ”€β”€ Client Mobile: 0.1.0 βœ… -β”œβ”€β”€ Web Dashboard: TBD ⏳ -β”œβ”€β”€ Command API: 0.1.0 βœ… -└── Core API: 0.1.0 βœ… - -In Staging (Testing): -β”œβ”€β”€ Staff Mobile: 0.2.0 πŸ”„ (50% through QA) -β”œβ”€β”€ Client Mobile: 0.2.0 πŸ”„ (50% through QA) -└── Web Dashboard: 0.1.0 πŸ”„ (30% through QA) - -Next Production Release: -β”œβ”€β”€ Target Date: March 15, 2026 -β”œβ”€β”€ Products: All 5 products -β”œβ”€β”€ Focus: Shift booking, payments, mobile improvements -└── Expected Impact: 2-3 hour deployment window - -Risks & Blockers: None current - -Recent Incidents: None -``` - ---- - -**Document Version**: 1.0 -**Created**: 2026-03-05 -**Maintain**: DevOps / Release Manager diff --git a/RELEASE_WORKFLOW.md b/RELEASE_WORKFLOW.md deleted file mode 100644 index 8bac0b80..00000000 --- a/RELEASE_WORKFLOW.md +++ /dev/null @@ -1,382 +0,0 @@ -# Release Workflow Guide - -Quick reference for executing releases in the KROW Workforce monorepo. - -## πŸš€ Quick Start Release (for a single product) - -### Example: Release Staff Mobile v0.2.0 - -```bash -# 1. Start from main branch -git checkout main -git pull origin main - -# 2. Create release branch -git checkout -b release/staff-mobile-v0.2.0 - -# 3. Update version numbers -# File: apps/mobile/apps/staff_app/pubspec.yaml -# Change: version: 0.1.0+5 β†’ version: 0.2.0+6 - -# 4. Update CHANGELOG.md -nano CHANGELOG.md -# Add entry at top: -# | 2026-03-05 | Staff Mobile 0.2.0 | [Feature/fix descriptions] | - -# 5. Commit changes -git add . -git commit -m "chore(staff-mobile): bump version to 0.2.0" - -# 6. Push release branch -git push origin release/staff-mobile-v0.2.0 - -# 7. Create pull request on GitHub -# (GitHub CLI: gh pr create --title "Release: Staff Mobile v0.2.0" --body "See RELEASE_STRATEGY.md") - -# 8. Merge to main after approval -git checkout main -git pull origin main -git merge --ff-only release/staff-mobile-v0.2.0 - -# 9. Create git tag -git tag -a staff-mobile/dev-v0.2.0 -m "Staff Mobile v0.2.0 - [Feature description]" - -# 10. Push tag -git push origin staff-mobile/dev-v0.2.0 - -# 11. Create GitHub Release -# - Go to Releases β†’ Draft a new release -# - Tag: staff-mobile/dev-v0.2.0 -# - Title: "Staff Mobile v0.2.0" -# - Description: Copy from CHANGELOG -# - Attach APK/AAB if available -# - Publish -``` - ---- - -## πŸ”„ Multi-Product Coordinated Release - -### Step-by-Step for v1.0.0 Release (all products) - -#### Phase 1: Preparation (48 hours before) - -```bash -# Check all tests pass -make test -make test-backend -make test-web - -# Verify builds -make build-mobile-dev -make build-web - -# No lint errors -make lint -``` - -#### Phase 2: Version Bumping - -**File locations to update:** - -1. **Mobile Apps**: `apps/mobile/apps/staff_app/pubspec.yaml` (and client_app) - ```yaml - version: 1.0.0+1 # Increment build number - ``` - -2. **Web Dashboard**: `apps/web/package.json` - ```json - "version": "1.0.0" - ``` - -3. **Command API**: `backend/command-api/package.json` - ```json - "version": "1.0.0" - ``` - -4. **Core API**: `backend/core-api/package.json` - ```json - "version": "1.0.0" - ``` - -5. **CodeMagic**: `codemagic.yaml` - ```yaml - build_version: "1.0.0" - ``` - -6. **CHANGELOG.md**: Add entry at top - ```markdown - | 2026-03-15 | 1.0.0 | Full feature v1.0.0 release [all products] | - ``` - -```bash -# Commit all version bumps -git add -A -git commit -m "chore: bump all products to v1.0.0" -``` - -#### Phase 3: Staging Release - -```bash -# Create release branch -git checkout -b release/v1.0.0-staging - -# Push and merge (or direct commit to release branch) -git push origin release/v1.0.0-staging - -# Tag all products with staging -git tag -a web-dashboard/staging-v1.0.0 -m "v1.0.0 staging release" -git tag -a command-api/staging-v1.0.0 -m "v1.0.0 staging release" -git tag -a core-api/staging-v1.0.0 -m "v1.0.0 staging release" -git tag -a staff-mobile/staging-v1.0.0 -m "v1.0.0 staging release" -git tag -a client-mobile/staging-v1.0.0 -m "v1.0.0 staging release" - -# Push all staging tags -git push origin --tags - -# Deploy to staging environment -./scripts/deploy-staging.sh # (create if needed) -``` - -#### Phase 4: QA & Testing - -- [ ] Smoke test all features -- [ ] Performance tests -- [ ] Security scan -- [ ] API contract verification - -#### Phase 5: Production Release - -```bash -# Create production tags (after staging approval) -git tag -a web-dashboard/prod-v1.0.0 -m "v1.0.0 production release" -git tag -a command-api/prod-v1.0.0 -m "v1.0.0 production release" -git tag -a core-api/prod-v1.0.0 -m "v1.0.0 production release" -git tag -a staff-mobile/prod-v1.0.0 -m "v1.0.0 production release" -git tag -a client-mobile/prod-v1.0.0 -m "v1.0.0 production release" - -# Push tags -git push origin --tags - -# Deploy in dependency order -./scripts/deploy-prod-dataconnect.sh -./scripts/deploy-prod-backend.sh -./scripts/deploy-prod-web.sh -./scripts/deploy-prod-mobile.sh -``` - ---- - -## πŸ”₯ Hotfix Release (Emergency Production Fix) - -### Example: Critical bug in Staff Mobile v1.0.0 β†’ v1.0.1 - -```bash -# 1. Create hotfix branch from production tag -git checkout -b hotfix/staff-mobile-v1.0.1 staff-mobile/prod-v1.0.0 - -# 2. Fix the bug -git add -git commit -m "fix: [critical bug description]" - -# 3. Update version (PATCH bump only) -# apps/mobile/apps/staff_app/pubspec.yaml -# Change: 1.0.0+1 β†’ 1.0.1+2 - -# 4. Update CHANGELOG -nano CHANGELOG.md -# Add: | 2026-03-15 | Staff Mobile 1.0.1 | Hotfix: [bug description] | - -# 5. Push hotfix branch -git push origin hotfix/staff-mobile-v1.0.1 - -# 6. Create PR for review (expedited) -gh pr create --title "Hotfix: Staff Mobile v1.0.1" \ - --body "EMERGENCY: Critical issue fix\n\nSee CHANGELOG.md for details" - -# 7. Merge to main (fast-track approval) -git checkout main -git pull origin main -git merge --ff-only hotfix/staff-mobile-v1.0.1 - -# 8. Tag production immediately -git tag -a staff-mobile/prod-v1.0.1 -m "Hotfix: [description]" -git push origin staff-mobile/prod-v1.0.1 - -# 9. Deploy to production -./scripts/deploy-prod-mobile-staff.sh - -# 10. Create GitHub Release with "HOTFIX" in title -``` - ---- - -## πŸ“Š Useful Git Commands - -### View all tags for a product -```bash -git tag -l "staff-mobile/*" --sort=-version:refname -git tag -l "*/prod-v*" --sort=-version:refname -``` - -### View tag details -```bash -git show staff-mobile/prod-v1.0.0 -git log staff-mobile/prod-v1.0.0...staff-mobile/prod-v0.9.0 # Changes between versions -``` - -### List tags created in last week -```bash -git log --oneline --decorate --tags --since="1 week ago" -``` - -### See all commits since last tag -```bash -git log ..HEAD --oneline -``` - -### Delete a tag (if mistake) -```bash -# Local -git tag -d staff-mobile/dev-v0.1.0 - -# Remote -git push origin --delete staff-mobile/dev-v0.1.0 -``` - -### Create lightweight tag (simpler, no message) -```bash -git tag staff-mobile/dev-v0.1.0 -``` - ---- - -## πŸ€– Automation Scripts (Create These) - -### Create: `scripts/tag-all-products.sh` - -```bash -#!/bin/bash -# Usage: ./scripts/tag-all-products.sh prod 1.0.0 - -ENV=$1 # dev, staging, prod -VERSION=$2 # e.g., 1.0.0 - -if [ -z "$ENV" ] || [ -z "$VERSION" ]; then - echo "Usage: $0 " - echo "Example: $0 prod 1.0.0" - exit 1 -fi - -PRODUCTS=( - "staff-mobile" - "client-mobile" - "web-dashboard" - "command-api" - "core-api" -) - -for product in "${PRODUCTS[@]}"; do - TAG="${product}/${ENV}-v${VERSION}" - echo "Creating tag: $TAG" - git tag -a "$TAG" -m "$product v$VERSION - $ENV release" -done - -echo "Pushing all tags..." -git push origin --tags - -echo "βœ… All products tagged for $ENV-v$VERSION" -``` - -### Create: `scripts/show-version-matrix.sh` - -```bash -#!/bin/bash -# Show version matrix of all products - -echo "πŸ“¦ KROW Workforce Version Matrix" -echo "================================" -echo "" - -PRODUCTS=( - "staff-mobile" - "client-mobile" - "web-dashboard" - "command-api" - "core-api" -) - -ENVS=("dev" "staging" "prod") - -for env in "${ENVS[@]}"; do - echo "=== $ENV Environment ===" - for product in "${PRODUCTS[@]}"; do - TAGS=$(git tag -l "${product}/${env}-v*" --sort=-version:refname | head -1) - if [ -z "$TAGS" ]; then - echo " $product: (no tags)" - else - echo " $product: $TAGS" - fi - done - echo "" -done -``` - ---- - -## βœ… Release Checklist Template - -Copy this for each release: - -```markdown -## Release: [Product] v[Version] - -**Release Date**: [Date] -**Release Manager**: [Name] - -### Pre-Release (48h before) -- [ ] All PRs merged and reviewed -- [ ] Tests passing (unit + integration) -- [ ] No lint/type errors -- [ ] Mobile builds succeed on CodeMagic -- [ ] Performance benchmarks acceptable -- [ ] Security scan passed -- [ ] CHANGELOG.md updated -- [ ] Documentation updated - -### Release Day -- [ ] Create release branch: `release/[product]-v[version]` -- [ ] Bump version numbers in all files -- [ ] Commit: `chore: bump [product] to v[version]` -- [ ] Create tag: `[product]/staging-v[version]` -- [ ] Deploy to staging -- [ ] Smoke tests passed -- [ ] Create GitHub Release page - -### Post-Release (24h after) -- [ ] Monitor error logs -- [ ] Verify features work end-to-end -- [ ] Create production tag (if approved) -- [ ] Deploy to production -- [ ] Final verification -- [ ] Notify users - -### Rollback Plan (if needed) -- [ ] Identified issue -- [ ] Created hotfix branch -- [ ] Tagged hotfix version -- [ ] Deployed rollback -- [ ] Post-mortem created -``` - ---- - -## πŸ”— Related Files - -- [RELEASE_STRATEGY.md](./RELEASE_STRATEGY.md) - Full strategy document -- [CHANGELOG.md](./CHANGELOG.md) - Version history -- [codemagic.yaml](./codemagic.yaml) - CI/CD configuration - ---- - -**Last Updated**: 2026-03-05 diff --git a/VERSION_FILES_REFERENCE.md b/VERSION_FILES_REFERENCE.md deleted file mode 100644 index 2def7643..00000000 --- a/VERSION_FILES_REFERENCE.md +++ /dev/null @@ -1,406 +0,0 @@ -# Version File Locations Reference - -When releasing a product, update version numbers in **all applicable files**. Use this checklist to ensure nothing is missed. - ---- - -## πŸ“± Staff Mobile App Release - -**All files to update when releasing staff mobile app:** - -### 1. Pubspec.yaml -**File**: `/apps/mobile/apps/staff_app/pubspec.yaml` - -```yaml -# Current state (example) -version: 0.1.0+5 - -# Change to (example for v0.2.0) -version: 0.2.0+6 -``` - -**Rules**: -- Format: `MAJOR.MINOR.PATCH+BUILD_NUMBER` -- Always increment BUILD_NUMBER -- For each new version, start BUILD_NUMBER at +1 - -### 2. CodeMagic Configuration -**File**: `/codemagic.yaml` - -Find the `mobile-client-build` workflow section: - -```yaml -workflows: - mobile-client-build: - name: Mobile Client Build - - environment: - # ... other env vars ... - groups: - - default - - mobile-staff-build # ← This group might have version - - on_success: - - | - VERSION=$(grep "^version:" apps/mobile/apps/staff_app/pubspec.yaml | cut -d' ' -f2) - echo "Version: $VERSION" # This auto-reads from pubspec -``` - -**Note**: CodeMagic typically reads version from pubspec.yaml automatically. Update only if you have hardcoded version strings. - -### 3. CHANGELOG.md -**File**: `/CHANGELOG.md` - -Add entry at **very top** of the table: - -```markdown -| Date | Version | Change | -|---|---|---| -| 2026-03-05 | Staff Mobile 0.2.0 | [Feature descriptions] | -| 2026-03-01 | 0.1.25 | Previous entry... | -``` - ---- - -## πŸ“± Client Mobile App Release - -**All files to update when releasing client mobile app:** - -### 1. Pubspec.yaml -**File**: `/apps/mobile/apps/client_app/pubspec.yaml` - -```yaml -# Update format same as staff app -version: 0.2.0+6 -``` - -### 2. CodeMagic Configuration -**File**: `/codemagic.yaml` - -Find the `mobile-staff-build` workflow (NOT client-build): - -```yaml -workflows: - mobile-staff-build: # ← Staff app config - # ... update pubspec reference for staff ... - - mobile-client-build: # ← Client app config (if separate) - # ... update pubspec reference for client ... -``` - -### 3. CHANGELOG.md -**File**: `/CHANGELOG.md` - -```markdown -| Date | Version | Change | -|---|---|---| -| 2026-03-05 | Client Mobile 0.2.0 | [Feature descriptions] | -``` - ---- - -## 🌐 Web Dashboard Release - -**All files to update when releasing web dashboard:** - -### 1. Package.json -**File**: `/apps/web/package.json` - -```json -{ - "name": "web", - "private": true, - "version": "0.1.0", ← Update this - // ... other fields ... -} -``` - -**Format**: `X.Y.Z` (semantic versioning) - -### 2. CHANGELOG.md -**File**: `/CHANGELOG.md` - -```markdown -| Date | Version | Change | -|---|---|---| -| 2026-03-05 | Web Dashboard 0.1.0 | [Feature descriptions] | -``` - -### 3. Environment/Build Files (Optional) -Check if there are any other version references: - -```bash -# Search for version strings -grep -r "0.0.0" apps/web/ -grep -r "VERSION" apps/web/ -``` - ---- - -## πŸ”§ Command API Backend Release - -**All files to update when releasing command API:** - -### 1. Package.json -**File**: `/backend/command-api/package.json` - -```json -{ - "name": "@krow/command-api", - "version": "0.2.0", ← Update this - // ... other fields ... -} -``` - -### 2. Docker Configuration (if applicable) -**File**: `/backend/command-api/Dockerfile` - -If you tag Docker images: - -```dockerfile -FROM node:20-alpine - -# Add label with version -LABEL version="0.2.0" -LABEL description="KROW Command API v0.2.0" -``` - -### 3. CHANGELOG.md -**File**: `/CHANGELOG.md` - -```markdown -| Date | Version | Change | -|---|---|---| -| 2026-03-05 | Command API 0.2.0 | [Feature descriptions] | -``` - -### 4. Environment Configuration (if applicable) -If there's a `.env` or config file: - -```bash -# Check for any version references -grep -r "VERSION\|version" backend/command-api/ -``` - ---- - -## πŸ”§ Core API Backend Release - -**All files to update when releasing core API:** - -### 1. Package.json -**File**: `/backend/core-api/package.json` - -```json -{ - "name": "@krow/core-api", - "version": "0.2.0", ← Update this - // ... other fields ... -} -``` - -### 2. CHANGELOG.md -**File**: `/CHANGELOG.md` - -```markdown -| Date | Version | Change | -|---|---|---| -| 2026-03-05 | Core API 0.2.0 | [Feature descriptions] | -``` - -### Other Files -Same as Command API (Docker, config files, etc.) - ---- - -## πŸ—„οΈ DataConnect Database Schema Release - -**Note**: DataConnect versions are typically managed separately through schema versioning. - -### 1. Schema Version File (if exists) -**File**: Check in `/backend/dataconnect/` - -```yaml -# Example structure -schema_version: 0.3.0 -created_at: 2026-03-05 -description: "Schema version 0.3.0 - [description]" -``` - -### 2. CHANGELOG.md -**File**: `/CHANGELOG.md` - -```markdown -| Date | Version | Change | -|---|---|---| -| 2026-03-05 | DataConnect Schema 0.3.0 | [Schema changes] | -``` - ---- - -## βœ… Release Checklist: Version File Updates - -### When releasing Staff Mobile v0.2.0 - -- [ ] `/apps/mobile/apps/staff_app/pubspec.yaml` β†’ `0.2.0+X` -- [ ] `/codemagic.yaml` β†’ version string (if hardcoded) -- [ ] `/CHANGELOG.md` β†’ Add entry with date + version -- [ ] Commit: `git add . && git commit -m "chore: staff mobile v0.2.0"` -- [ ] Tag: `git tag -a staff-mobile/dev-v0.2.0 -m "Staff Mobile v0.2.0"` -- [ ] Verify: `git show staff-mobile/dev-v0.2.0` - -### When releasing Client Mobile v0.2.0 - -- [ ] `/apps/mobile/apps/client_app/pubspec.yaml` β†’ `0.2.0+X` -- [ ] `/codemagic.yaml` β†’ version string (if hardcoded) -- [ ] `/CHANGELOG.md` β†’ Add entry -- [ ] Complete release process (commit β†’ tag β†’ verify) - -### When releasing Web Dashboard v0.1.0 - -- [ ] `/apps/web/package.json` β†’ `"version": "0.1.0"` -- [ ] `/CHANGELOG.md` β†’ Add entry -- [ ] Complete release process - -### When releasing Command API v0.2.0 - -- [ ] `/backend/command-api/package.json` β†’ `"version": "0.2.0"` -- [ ] `/backend/command-api/Dockerfile` β†’ Label update (optional) -- [ ] `/CHANGELOG.md` β†’ Add entry -- [ ] Complete release process - -### When releasing Core API v0.2.0 - -- [ ] `/backend/core-api/package.json` β†’ `"version": "0.2.0"` -- [ ] `/backend/core-api/Dockerfile` β†’ Label update (optional) -- [ ] `/CHANGELOG.md` β†’ Add entry -- [ ] Complete release process - -### When releasing All Products (Synchronized Release) - -- [ ] Staff Mobile: Update pubspec + codemagic -- [ ] Client Mobile: Update pubspec + codemagic -- [ ] Web: Update package.json -- [ ] Command API: Update package.json + docker -- [ ] Core API: Update package.json + docker -- [ ] **CHANGELOG.md**: Add comprehensive entry with all products -- [ ] Single commit: `git commit -m "chore: release all products v1.0.0"` -- [ ] Multiple tags (one per product): - ```bash - git tag -a staff-mobile/prod-v1.0.0 -m "v1.0.0" - git tag -a client-mobile/prod-v1.0.0 -m "v1.0.0" - git tag -a web-dashboard/prod-v1.0.0 -m "v1.0.0" - git tag -a command-api/prod-v1.0.0 -m "v1.0.0" - git tag -a core-api/prod-v1.0.0 -m "v1.0.0" - git push origin --tags - ``` - ---- - -## πŸ” Verify All Updates - -After updating versions, verify nothing was missed: - -```bash -# Search for old version strings still remaining -grep -r "0.1.0" apps/mobile/ --include="*.yaml" --include="*.yml" --include="*.json" -grep -r "0.0.0" apps/web/ --include="*.json" -grep -r "0.1.0" backend/ --include="*.json" - -# Check CHANGELOG was updated -head -5 CHANGELOG.md - -# Verify git status shows all changes -git status - -# Review exact changes before committing -git diff CHANGELOG.md -git diff apps/mobile/apps/staff_app/pubspec.yaml -git diff apps/web/package.json -``` - ---- - -## πŸ“ Version Update Template - -Copy this template for each release: - -```bash -#!/bin/bash -# Release: [Product] v[Version] -# Date: [Date] - -# Update Staff Mobile -sed -i '' 's/version: 0.1.0+5/version: 0.2.0+6/' apps/mobile/apps/staff_app/pubspec.yaml - -# Update CHANGELOG -# (Manual: Add entry at top with date and version) - -# Verify -grep "^version:" apps/mobile/apps/staff_app/pubspec.yaml -head -3 CHANGELOG.md - -# Commit -git add -A -git commit -m "chore: bump staff mobile to v0.2.0" - -# 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 - -# Done! -echo "βœ… Release complete. Tag: staff-mobile/dev-v0.2.0" -``` - ---- - -## 🚨 Common Mistakes - -❌ **Forgot to update pubspec.yaml** -- Result: Version mismatch between code and git tag - -❌ **Updated CHANGELOG but forgot to update package.json** -- Result: Version inconsistency, harder to debug - -❌ **Updated version but didn't increment build number (mobile)** -- Result: Build tools may fail or warn - -❌ **Forgot to update codemagic.yaml** -- Result: CI/CD may deploy old version - -❌ **Updated multiple files but forgot to commit CHANGELOG** -- Result: Historical record lost - -βœ… **Always:** -1. Update ALL version files -2. Update CHANGELOG.md -3. Commit ALL changes together -4. Tag after commit -5. Verify with `git show ` - ---- - -## 🎯 Pro Tips - -**Tip 1**: Use a script to update all versions at once - -```bash -# Create update-version.sh -VERSION="0.2.0" -sed -i '' "s/version:.*/version: $VERSION/" apps/mobile/apps/staff_app/pubspec.yaml -sed -i '' "s/\"version\".*/\"version\": \"$VERSION\"/" apps/web/package.json -# ... etc for all files -``` - -**Tip 2**: Automate version bumping based on git commit messages - -Use conventional commits (`feat:`, `fix:`, `BREAKING CHANGE:`) to auto-determine MAJOR/MINOR/PATCH - -**Tip 3**: Use GitHub Actions to auto-create tags - -Create an action that tags on PR merge with version from package.json - ---- - -**Last Updated**: 2026-03-05 -**Maintain**: DevOps Team