From 085445e73080bfff9562c5b6f82d753d69cd9445 Mon Sep 17 00:00:00 2001 From: Achintha Isuru Date: Thu, 5 Mar 2026 10:49:09 -0500 Subject: [PATCH 01/15] feat: add comprehensive release process documentation and version file references - Introduced RELEASE_VISUAL_GUIDE.md for a visual overview of the release pipeline, including development, staging, and production phases. - Created RELEASE_WORKFLOW.md detailing step-by-step release procedures for single and multi-product releases, including hotfix processes. - Added VERSION_FILES_REFERENCE.md to outline all necessary version file updates for each product during releases, ensuring consistency and completeness. --- RELEASE_IMPLEMENTATION.md | 509 ++++++++++++++++++++++++ RELEASE_INDEX.md | 411 +++++++++++++++++++ RELEASE_PACKAGE_SUMMARY.md | 507 ++++++++++++++++++++++++ RELEASE_QUICK_REFERENCE.md | 267 +++++++++++++ RELEASE_STRATEGY.md | 425 ++++++++++++++++++++ RELEASE_VISUAL_GUIDE.md | 382 ++++++++++++++++++ RELEASE_WORKFLOW.md | 382 ++++++++++++++++++ VERSION_FILES_REFERENCE.md | 406 +++++++++++++++++++ apps/mobile/apps/client/pubspec.yaml | 2 +- apps/mobile/apps/staff/pubspec.yaml | 2 +- docs/RELEASE/HOTFIX_PROCESS.md | 343 ++++++++++++++++ docs/RELEASE/MOBILE_RELEASE_PLAN.md | 564 +++++++++++++++++++++++++++ docs/RELEASE/OVERALL_RELEASE_PLAN.md | 452 +++++++++++++++++++++ 13 files changed, 4650 insertions(+), 2 deletions(-) create mode 100644 RELEASE_IMPLEMENTATION.md create mode 100644 RELEASE_INDEX.md create mode 100644 RELEASE_PACKAGE_SUMMARY.md create mode 100644 RELEASE_QUICK_REFERENCE.md create mode 100644 RELEASE_STRATEGY.md create mode 100644 RELEASE_VISUAL_GUIDE.md create mode 100644 RELEASE_WORKFLOW.md create mode 100644 VERSION_FILES_REFERENCE.md create mode 100644 docs/RELEASE/HOTFIX_PROCESS.md create mode 100644 docs/RELEASE/MOBILE_RELEASE_PLAN.md create mode 100644 docs/RELEASE/OVERALL_RELEASE_PLAN.md diff --git a/RELEASE_IMPLEMENTATION.md b/RELEASE_IMPLEMENTATION.md new file mode 100644 index 00000000..3af3c020 --- /dev/null +++ b/RELEASE_IMPLEMENTATION.md @@ -0,0 +1,509 @@ +# 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 new file mode 100644 index 00000000..1874c655 --- /dev/null +++ b/RELEASE_INDEX.md @@ -0,0 +1,411 @@ +# 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 new file mode 100644 index 00000000..5557874e --- /dev/null +++ b/RELEASE_PACKAGE_SUMMARY.md @@ -0,0 +1,507 @@ +# 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 new file mode 100644 index 00000000..b1dfbe88 --- /dev/null +++ b/RELEASE_QUICK_REFERENCE.md @@ -0,0 +1,267 @@ +# 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 new file mode 100644 index 00000000..a220e8db --- /dev/null +++ b/RELEASE_STRATEGY.md @@ -0,0 +1,425 @@ +# 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 new file mode 100644 index 00000000..f7646d11 --- /dev/null +++ b/RELEASE_VISUAL_GUIDE.md @@ -0,0 +1,382 @@ +# 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 new file mode 100644 index 00000000..8bac0b80 --- /dev/null +++ b/RELEASE_WORKFLOW.md @@ -0,0 +1,382 @@ +# 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 new file mode 100644 index 00000000..2def7643 --- /dev/null +++ b/VERSION_FILES_REFERENCE.md @@ -0,0 +1,406 @@ +# 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 diff --git a/apps/mobile/apps/client/pubspec.yaml b/apps/mobile/apps/client/pubspec.yaml index f9e3d656..677133d7 100644 --- a/apps/mobile/apps/client/pubspec.yaml +++ b/apps/mobile/apps/client/pubspec.yaml @@ -1,7 +1,7 @@ name: krowwithus_client description: "KROW Client Application" publish_to: "none" -version: 0.0.1-IlianaClientM3 +version: 0.0.1-m4 resolution: workspace environment: diff --git a/apps/mobile/apps/staff/pubspec.yaml b/apps/mobile/apps/staff/pubspec.yaml index 457446fd..21c19091 100644 --- a/apps/mobile/apps/staff/pubspec.yaml +++ b/apps/mobile/apps/staff/pubspec.yaml @@ -1,7 +1,7 @@ name: krowwithus_staff description: "KROW Staff Application" publish_to: 'none' -version: 0.0.1-IlianaStaffM3 +version: 0.0.1-m4 resolution: workspace environment: diff --git a/docs/RELEASE/HOTFIX_PROCESS.md b/docs/RELEASE/HOTFIX_PROCESS.md new file mode 100644 index 00000000..313b9be6 --- /dev/null +++ b/docs/RELEASE/HOTFIX_PROCESS.md @@ -0,0 +1,343 @@ +# Hotfix Process + +**For Emergency Production Fixes** + +--- + +## 🚨 When to Hotfix + +Use hotfix when: +- βœ… Critical bug in production affecting users +- βœ… Data loss or security vulnerability +- βœ… Service unavailable or major feature broken +- βœ… Customer-blocking issue + +**Don't use hotfix for:** +- ❌ Minor bugs (can wait for next release) +- ❌ Feature requests +- ❌ Nice-to-have improvements +- ❌ Styling issues + +--- + +## πŸ”„ Hotfix Process + +### Step 1: Assess & Declare Emergency + +``` +Issue: [Brief description] +Severity: CRITICAL / HIGH / MEDIUM +Product: [Staff Mobile / Client Mobile / Web / Backend] +Environment: Production +Impact: [How many users affected] +``` + +Once severity confirmed β†’ Start hotfix immediately. + +--- + +### Step 2: Create Hotfix Branch + +```bash +# From production tag +git checkout -b hotfix/krow-withus-worker-mobile-v0.1.1 \ + krow-withus-worker-mobile/prod-v0.1.0 + +# Verify you're on the right tag +git log -1 --oneline +``` + +**Format**: `hotfix/-v` + +--- + +### Step 3: Fix the Bug + +```bash +# Make your fix +# Edit files, test locally + +# Commit with clear message +git commit -m "fix: [issue description] + +HOTFIX for production +Issue: [what happened] +Solution: [what was fixed] +Tested: [how was it tested locally]" +``` + +**Keep it minimal:** +- Only fix the specific bug +- Don't refactor or optimize +- Don't add new features + +--- + +### Step 4: Update Version + +Update PATCH version only (0.1.0 β†’ 0.1.1): + +**For Mobile** (`apps/mobile/apps/*/pubspec.yaml`): +```yaml +# Old +version: 0.1.0+5 + +# New +version: 0.1.1+6 # Only PATCH changed +``` + +**For Web** (`apps/web/package.json`): +```json +"version": "0.1.1" +``` + +**For Backend** (`backend/*/package.json`): +```json +"version": "0.1.1" +``` + +--- + +### Step 5: Update CHANGELOG + +Add entry to **top** of appropriate CHANGELOG: + +```markdown +| 2026-03-05 | 0.1.1 | HOTFIX: [Issue fixed] | + +(previous entries below...) +``` + +--- + +### Step 6: Code Review (Expedited) + +```bash +# Push hotfix branch +git push origin hotfix/krow-withus-worker-mobile-v0.1.1 + +# Create PR on GitHub with URGENT label +gh pr create --title "HOTFIX: [Issue description]" \ + --body "**URGENT PRODUCTION FIX** + +Issue: [What was broken] +Impact: [Users affected] +Solution: [What was fixed] +Testing: [Local verification]" +``` + +**Get approval within 15 minutes if possible.** + +--- + +### Step 7: Merge to Main + +```bash +# Review complete - merge +git checkout main +git pull origin main +git merge --ff-only hotfix/krow-withus-worker-mobile-v0.1.1 +git push origin main +``` + +--- + +### Step 8: Create Production Tag + +```bash +# Create tag from main +git tag -a krow-withus-worker-mobile/prod-v0.1.1 \ + -m "HOTFIX: [Issue fixed]" + +git push origin krow-withus-worker-mobile/prod-v0.1.1 +``` + +--- + +### Step 9: Deploy to Production + +```bash +# Follow your deployment procedure +# Higher priority than normal releases + +./scripts/deploy-mobile-production.sh krow-withus-worker-mobile/prod-v0.1.1 +``` + +**Deployment time**: Within 30 minutes of approval + +--- + +### Step 10: Verify & Monitor + +```bash +# Smoke tests +- App launches +- Core features work +- No new errors + +# Monitor for 2 hours +- Watch error logs +- Check user reports +- Verify fix worked +``` + +--- + +### Step 11: Communicate + +**Immediately after deployment:** + +```markdown +🚨 PRODUCTION HOTFIX DEPLOYED + +Product: Worker Mobile +Version: 0.1.1 +Issue: [Fixed issue] +Impact: [Resolved for X users] +Status: βœ… Deployed & verified + +No user action required. +Service restored to normal. +``` + +**24 hours later:** + +```markdown +βœ… HOTFIX STATUS UPDATE + +Production hotfix v0.1.1 deployed 24 hours ago. +Zero errors reported post-deployment. +System stable. + +Thank you for your patience! +``` + +--- + +## ⏱️ Timeline + +``` +T-0: Issue detected & reported +T+5min: Severity assessed, hotfix branch created +T+15: Fix implemented, code review started +T+30: Approved & merged, tag created +T+45: Deployed to production +T+60: Smoke tests pass, monitoring enabled +T+120: Declare emergency resolved, communicate +T+1day: Follow-up communication +``` + +**Total time: 2-4 hours from detection to resolution** + +--- + +## 🚫 Common Mistakes to Avoid + +❌ **Don't**: +- Skip code review (even in emergency) +- Add multiple unrelated fixes in one hotfix +- Forget to update version number +- Forget CHANGELOG entry +- Deploy without testing +- Forget to communicate with users + +βœ… **Do**: +- Keep hotfix minimal and focused +- Test every fix locally first +- Get at least one approval +- Update all version files +- Deploy immediately after approval +- Monitor actively for 2+ hours + +--- + +## πŸ“‹ Hotfix Checklist + +Copy for each emergency: + +``` +Hotfix: [Product] v[Old Version] β†’ v[New Version] + +β–‘ Severity assessed & documented +β–‘ Branch created from production tag +β–‘ Bug fixed & tested locally +β–‘ Version number updated (PATCH only) +β–‘ CHANGELOG entry added +β–‘ Commit message clear +β–‘ Code review requested (marked URGENT) +β–‘ Approval obtained +β–‘ Merged to main +β–‘ Production tag created +β–‘ Tag pushed to remote +β–‘ Deployed to production +β–‘ Smoke tests passed +β–‘ Error logs monitored (2+ hours) +β–‘ Users notified +β–‘ GitHub Release created +β–‘ Incident documented + +Total Time: ___ minutes +``` + +--- + +## πŸ” Post-Incident + +After emergency is resolved: + +1. **Document what happened** + - Root cause analysis + - Why it wasn't caught before + - What testing was missed + +2. **Schedule postmortem** (within 24 hours) + - Review what went wrong + - Discuss prevention + - Update processes if needed + +3. **Plan prevention** + - Add test coverage + - Update CI/CD checks + - Improve monitoring + +4. **Communicate findings** + - Share with team + - Update documentation + - Prevent recurrence + +--- + +## πŸ“ž Emergency Contacts + +When issue detected: + +1. **Notify**: + - Release Engineer + - DevOps + - Product Owner + - Affected Team + +2. **Communication Channel**: + - Slack: #emergency-releases + - Time-sensitive decisions on call + +3. **Decision Maker**: + - Product Owner approves rollback vs hotfix + - Release Engineer executes + - DevOps monitors infrastructure + +--- + +## πŸ”— Related + +- [OVERALL_RELEASE_PLAN.md](./OVERALL_RELEASE_PLAN.md) - Main release strategy +- [MOBILE_RELEASE_PLAN.md](./MOBILE_RELEASE_PLAN.md) - Mobile-specific process +- [../../CHANGELOG.md](../../CHANGELOG.md) - Version history + +--- + +**Last Updated**: 2026-03-05 +**Severity Levels**: +- πŸ”΄ CRITICAL: Service down, data loss, security (< 1 hour) +- 🟠 HIGH: Major feature broken, workaround available (< 4 hours) +- 🟑 MEDIUM: Minor feature affected (next release OK) diff --git a/docs/RELEASE/MOBILE_RELEASE_PLAN.md b/docs/RELEASE/MOBILE_RELEASE_PLAN.md new file mode 100644 index 00000000..c37dcc5b --- /dev/null +++ b/docs/RELEASE/MOBILE_RELEASE_PLAN.md @@ -0,0 +1,564 @@ +# Mobile App Release Plan + +**For Staff Mobile & Client Mobile Apps** + +--- + +## πŸ“± Overview + +This document covers release procedures for: + +- **Staff Mobile App** (aka "Worker Mobile") - `krow-withus-worker-mobile` +- **Client Mobile App** - `krow-withus-client-mobile` + +Both apps: +- Built with Flutter +- Distributed to iOS & Android app stores +- Maintain independent versions +- Have independent CHANGELOGs +- Share backend infrastructure + +--- + +## 🏷️ Tag & Release Naming + +### Tag Format + +``` +krow-withus--mobile/-v.. +``` + +### Examples + +**Staff Mobile (Worker Mobile)** +``` +krow-withus-worker-mobile/dev-v0.1.0 +krow-withus-worker-mobile/stage-v0.2.0 +krow-withus-worker-mobile/prod-v1.0.0 +krow-withus-worker-mobile/prod-v1.0.1-hotfix.1 +``` + +**Client Mobile** +``` +krow-withus-client-mobile/dev-v0.1.0 +krow-withus-client-mobile/stage-v0.2.0 +krow-withus-client-mobile/prod-v1.0.0 +``` + +### GitHub Release Names + +``` +Krow With Us - Worker Mobile - DEV - v0.1.0 +Krow With Us - Worker Mobile - STAGE - v0.2.0 +Krow With Us - Worker Mobile - PROD - v1.0.0 + +Krow With Us - Client Mobile - DEV - v0.1.0 +Krow With Us - Client Mobile - STAGE - v0.2.0 +Krow With Us - Client Mobile - PROD - v1.0.0 +``` + +--- + +## πŸ“ CHANGELOG Management + +### Location + +Each app has its own CHANGELOG in the `apps/mobile/` directory structure: + +``` +apps/mobile/ +β”œβ”€β”€ packages/ +β”‚ β”œβ”€β”€ features/ +β”‚ β”‚ β”œβ”€β”€ staff/ +β”‚ β”‚ β”‚ β”œβ”€β”€ authentication/CHANGELOG.md +β”‚ β”‚ β”‚ β”œβ”€β”€ home/CHANGELOG.md +β”‚ β”‚ β”‚ β”œβ”€β”€ payments/CHANGELOG.md +β”‚ β”‚ β”‚ β”œβ”€β”€ shifts/CHANGELOG.md +β”‚ β”‚ β”‚ └── ... (other staff features) +β”‚ β”‚ └── client/ +β”‚ β”‚ β”œβ”€β”€ dashboard/CHANGELOG.md +β”‚ β”‚ β”œβ”€β”€ orders/CHANGELOG.md +β”‚ β”‚ └── ... (other client features) +β”‚ └── ... (other packages) +β”œβ”€β”€ apps/ +β”‚ β”œβ”€β”€ staff_app/CHANGELOG.md ← Staff app root +β”‚ └── client_app/CHANGELOG.md ← Client app root +└── CHANGELOG.md ← Consolidated (optional) +``` + +### App-Level CHANGELOG Format + +**File**: `apps/mobile/apps/staff_app/CHANGELOG.md` + +```markdown +# Staff Mobile App - Change Log + +## [0.2.0] - 2026-03-15 + +### Added +- Feature X implementation +- Feature Y enhancement +- New UI component Z + +### Fixed +- Bug fix for issue #123 +- Crash when loading payments + +### Changed +- Updated design system +- Improved performance + +### Deprecated +- Removed old API endpoint + +## [0.1.0] - 2026-03-01 + +### Added +- Initial release +- Authentication with phone & OTP +- Shift browsing and booking +- Clock in/out functionality +- Payment history view +``` + +### Consolidated CHANGELOG (Optional) + +**File**: `apps/mobile/CHANGELOG.md` (at root of mobile folder) + +High-level overview of both apps: + +```markdown +# Krow Workforce - Mobile Apps - Change Log + +## Staff Mobile v0.2.0 + Client Mobile v0.1.0 - 2026-03-15 + +### Staff Mobile v0.2.0 +- Feature improvements +- Bug fixes + +### Client Mobile v0.1.0 +- Initial release + +## Previous versions... +``` + +--- + +## πŸ“ Version Files + +### Staff Mobile App + +**Primary Version File**: `apps/mobile/apps/staff_app/pubspec.yaml` + +```yaml +name: staff_app +description: "Krow With Us - Staff App" + +# Version format: MAJOR.MINOR.PATCH+BUILD_NUMBER +version: 0.1.0+1 + +environment: + sdk: '>=3.10.0 <4.0.0' + flutter: '>=3.38.0 <4.0.0' +``` + +**Rules**: +- Update version before each release +- Bump build number (+1) every build +- SemVer only for version part (before +) + +### Client Mobile App + +**Primary Version File**: `apps/mobile/apps/client_app/pubspec.yaml` + +```yaml +name: client_app +description: "Krow With Us - Client App" + +version: 0.1.0+1 + +environment: + sdk: '>=3.10.0 <4.0.0' + flutter: '>=3.38.0 <4.0.0' +``` + +--- + +## πŸš€ Release Workflow + +### Step 1: Create Release Branch + +```bash +cd /Users/achintha/Documents/GitHub/krow-workforce + +# For Staff Mobile +git checkout -b release/staff-mobile-v0.2.0 + +# For Client Mobile +git checkout -b release/client-mobile-v0.2.0 +``` + +--- + +### Step 2: Update Version Numbers + +#### Staff Mobile Example (v0.1.0 β†’ v0.2.0) + +**File**: `apps/mobile/apps/staff_app/pubspec.yaml` + +```yaml +# Old +version: 0.1.0+5 + +# New +version: 0.2.0+6 +``` + +#### Client Mobile Example (v0.1.0 β†’ v0.2.0) + +**File**: `apps/mobile/apps/client_app/pubspec.yaml` + +```yaml +# Old +version: 0.1.0+3 + +# New +version: 0.2.0+4 +``` + +--- + +### Step 3: Update CHANGELOG + +**File**: `apps/mobile/apps/staff_app/CHANGELOG.md` + +Add entry at **top**: + +```markdown +# Staff Mobile App - Change Log + +## [0.2.0] - 2026-03-05 + +### Added +- New shift details page with profile gating +- Benefits overview section +- Auto-match functionality + +### Fixed +- Payment history display bug +- Clock-in location verification + +### Changed +- Updated design system components +- Improved shift booking flow + +## [0.1.0] - 2026-02-15 +... +``` + +--- + +### Step 4: Commit Changes + +```bash +cd /Users/achintha/Documents/GitHub/krow-workforce + +# Stage changes +git add apps/mobile/apps/staff_app/pubspec.yaml +git add apps/mobile/apps/staff_app/CHANGELOG.md + +# Commit +git commit -m "chore(staff-mobile): bump version to 0.2.0 + +- Updated pubspec.yaml version: 0.1.0 β†’ 0.2.0 +- Updated build number: 5 β†’ 6 +- Updated CHANGELOG.md with v0.2.0 changes" +``` + +--- + +### Step 5: Create Pull Request + +```bash +# Push release branch +git push origin release/staff-mobile-v0.2.0 + +# Create PR (GitHub CLI) +gh pr create \ + --title "Release: Staff Mobile v0.2.0" \ + --body "## Release: Staff Mobile v0.2.0 + +### Changes +- See CHANGELOG.md for full list + +### Testing +- [ ] All tests passing +- [ ] Manual testing complete +- [ ] CodeMagic build successful + +### Checklist +- [x] Version updated +- [x] CHANGELOG updated +- [x] Branch created from main +- [ ] Approved by team lead" +``` + +--- + +### Step 6: Merge to Main + +Once PR is approved: + +```bash +# Switch to main +git checkout main +git pull origin main + +# Merge (fast-forward only) +git merge --ff-only release/staff-mobile-v0.2.0 + +# Push to remote +git push origin main + +# Delete release branch +git push origin --delete release/staff-mobile-v0.2.0 +``` + +--- + +### Step 7: Create Git Tag + +```bash +# For DEV release +git tag -a krow-withus-worker-mobile/dev-v0.2.0 \ + -m "Staff Mobile v0.2.0 - Dev Release + +Features: +- Shift details improvements +- Benefits overview +- Auto-match functionality + +Testing: +- All unit tests passing +- Manual QA on dev environment" + +# For STAGE release +git tag -a krow-withus-worker-mobile/stage-v0.2.0 \ + -m "Staff Mobile v0.2.0 - Stage Release" + +# For PROD release +git tag -a krow-withus-worker-mobile/prod-v0.2.0 \ + -m "Staff Mobile v0.2.0 - Production Release" +``` + +**Push tags**: + +```bash +git push origin krow-withus-worker-mobile/dev-v0.2.0 +git push origin krow-withus-worker-mobile/stage-v0.2.0 +git push origin krow-withus-worker-mobile/prod-v0.2.0 +``` + +--- + +### Step 8: Create GitHub Release + +1. Go to: GitHub β†’ Releases β†’ Draft a new release +2. Fill in: + +``` +Tag version: krow-withus-worker-mobile/dev-v0.2.0 + +Release title: +Krow With Us - Worker Mobile - DEV - v0.2.0 + +Description: + +## 🎯 What's New in v0.2.0 + +### ✨ Features +- Shift details page with profile completion gating +- Benefits overview with sick leave tracking +- Auto-match shift recommendations + +### πŸ”§ Improvements +- Faster payment history loading +- Better shift booking UX +- Improved clock-in reliability + +### πŸ› Bug Fixes +- Fixed payment display date issue +- Fixed location verification on iOS 15+ +- Fixed crash when no shifts available + +## πŸ“¦ Installation + +**iOS**: Download via TestFlight (internal) or App Store +**Android**: Download via Play Store + +## πŸ”— Dependencies + +Requires: +- Backend API v0.1.0+ +- DataConnect schema v0.3.0+ + +## ⚠️ Known Issues + +- Location permissions take 5-10 seconds on first install +- Workaround: Grant permissions in Settings app + +## πŸ“ Notes for QA + +- Test on actual device, not emulator +- Verify clock-in with GPS enabled +- Test all payment history edge cases + +--- + +Release Date: 2026-03-05 +Build Number: 6 +``` + +3. **Optional**: Attach build artifacts (APK/AAB from CodeMagic) +4. **Click**: "Publish release" + +--- + +## πŸ”„ Deployment Flow + +### Dev Release β†’ Staging + +After dev is tested: + +```bash +# Create stage tag from same commit +git tag -a krow-withus-worker-mobile/stage-v0.2.0 \ + krow-withus-worker-mobile/dev-v0.2.0 \ + -m "Staff Mobile v0.2.0 - Stage Release" + +git push origin krow-withus-worker-mobile/stage-v0.2.0 + +# Deploy using CodeMagic or manual process +``` + +### Staging Release β†’ Production + +After QA approval: + +```bash +# Create prod tag from same commit +git tag -a krow-withus-worker-mobile/prod-v0.2.0 \ + krow-withus-worker-mobile/stage-v0.2.0 \ + -m "Worker Mobile v0.2.0 - Production Release" + +git push origin krow-withus-worker-mobile/prod-v0.2.0 + +# Deploy to production +``` + +--- + +## πŸ“± App Store Distribution + +### iOS App Store + +**Version Name**: Match pubspec.yaml version (0.2.0) +**Build Number**: Match pubspec.yaml build number (+6) + +**Steps**: +1. Ensure TestFlight build passed +2. Submit to App Review +3. Apple reviews (3-5 days) +4. Release to users (can be phased) + +### Google Play Store + +**Version Name**: Match pubspec.yaml version (0.2.0) +**Version Code**: Match pubspec.yaml build number (6) + +**Steps**: +1. Upload APK/AAB from CodeMagic +2. Fill in release notes (from CHANGELOG) +3. Submit for review +4. Google reviews (hours to 24h) +5. Release to users (can be phased, e.g., 10% then 100%) + +--- + +## πŸ”§ Pre-Release Checklist + +Before creating tags: + +- [ ] All PRs merged to main +- [ ] Code review complete +- [ ] Tests passing (unit, widget, integration) +- [ ] No lint/analysis errors: `flutter analyze` +- [ ] Pubspec.yaml version updated +- [ ] Build number incremented +- [ ] CHANGELOG.md updated with date +- [ ] Screenshots prepared (fresh) +- [ ] Release notes drafted +- [ ] No hardcoded strings (use translations) +- [ ] No debug prints remaining +- [ ] Performance acceptable (app launch < 3 seconds) +- [ ] Screen lock/unlock works +- [ ] Deep links tested +- [ ] Notifications working +- [ ] GPS/location working +- [ ] Camera permissions working +- [ ] All user-facing text reviewed + +--- + +## 🎯 Release Cadence + +### Development Releases (dev) + +- **Frequency**: Weekly +- **Day**: Monday 10:00 UTC +- **Process**: Quick, test in dev only + +### Staging Releases (stage) + +- **Frequency**: Bi-weekly (on sprint/feature completion) +- **Day**: Wednesday before production +- **Process**: Full QA testing, 1 week in staging + +### Production Releases (prod) + +- **Frequency**: Monthly (end of sprint) +- **Day**: Sunday/Monday morning (low traffic) +- **Process**: Full validation, market distribution + +--- + +## πŸ”— Related + +- [OVERALL_RELEASE_PLAN.md](./OVERALL_RELEASE_PLAN.md) - General strategy +- [HOTFIX_PROCESS.md](./HOTFIX_PROCESS.md) - Emergency procedures +- [../../CHANGELOG.md](../../CHANGELOG.md) - Root-level history + +--- + +## πŸ“ž Common Questions + +**Q: What if I need to release just one app (not both)?** +A: Completely fine! Each app is independent. Release when ready. + +**Q: Do I need to update the root CHANGELOG?** +A: Optional. If you do, keep it high-level and reference app-specific CHANGELOGs. + +**Q: What about shared packages inside mobile/?** +A: If shared package updated, mention in both app CHANGELOGs. + +**Q: How do I handle breaking changes?** +A: MAJOR version bump (0.x β†’ 1.x) and clearly document in CHANGELOG. + +**Q: Can I release dev and stage on different days?** +A: Yes, no fixed schedule for dev/stage. Prod should be consistent (Sundays). + +--- + +**Last Updated**: 2026-03-05 +**Owner**: Mobile Engineering Team +**Status**: Active diff --git a/docs/RELEASE/OVERALL_RELEASE_PLAN.md b/docs/RELEASE/OVERALL_RELEASE_PLAN.md new file mode 100644 index 00000000..9ef4785f --- /dev/null +++ b/docs/RELEASE/OVERALL_RELEASE_PLAN.md @@ -0,0 +1,452 @@ +# KROW Workforce - Overall Release Plan + +**Document Version**: 1.0 +**Created**: 2026-03-05 +**Last Updated**: 2026-03-05 +**Product Scope**: All products (Mobile, Web, Backend, Database) + +--- + +## πŸ“‹ Overview + +This document outlines the release strategy for KROW Workforce monorepo containing 5 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** (Firebase Data Connect with PostgreSQL) + +--- + +## πŸ”— Versioning Strategy + +### Semantic Versioning (SemVer) + +All products use **Semantic Versioning 2.0.0**: + +``` +MAJOR.MINOR.PATCH-QUALIFIER +0.1.0 +1.2.3-rc.1 +``` + +- **MAJOR** (0β†’1): Breaking changes, major features +- **MINOR** (1β†’2): Backward-compatible new features +- **PATCH** (3β†’4): Bug fixes, minor improvements +- **QUALIFIER** (optional): `-rc.1`, `-beta.1`, `-hotfix.1` + +### Version Independence + +Each product maintains **independent versioning**: +- Products release on their own schedule +- No requirement to synchronize versions +- Can release major updates independently + +--- + +## 🏷️ Git Tag Naming Convention + +### Standard Format + +``` +/-v.. +``` + +### Products & Environments + +| Product | Tag Prefix | Environments | +|---------|-----------|---------------| +| Staff Mobile | `krow-withus-worker-mobile` | dev, stage, prod | +| Client Mobile | `krow-withus-client-mobile` | dev, stage, prod | +| Web Dashboard | `web-dashboard` | dev, stage, prod | +| Command API | `command-api` | dev, stage, prod | +| Core API | `core-api` | dev, stage, prod | +| DataConnect | `dataconnect` | stage, prod | + +### Environments + +- **dev**: Development releases (daily/weekly), unstable +- **stage**: Staging releases (bi-weekly), pre-production testing +- **prod**: Production releases (monthly), stable, customer-facing + +### Examples + +``` +krow-withus-worker-mobile/dev-v0.1.0 +krow-withus-client-mobile/stage-v0.2.0 +web-dashboard/prod-v1.0.0 +command-api/dev-v0.2.1 +core-api/prod-v0.1.0 +``` + +--- + +## πŸ“… Release Cadence + +### Development Releases (dev) + +- **Frequency**: Weekly or as-needed +- **Scope**: Feature completions, bug fixes +- **Duration**: Not guaranteed stable +- **Deployment**: Dev environment only +- **Who**: Development team + +### Staging Releases (stage) + +- **Frequency**: Bi-weekly (typically mid/end of sprint) +- **Scope**: Sprint completion, feature milestones +- **Duration**: 1-2 weeks stability expected +- **Deployment**: Staging environment for QA +- **Who**: QA team validates + +### Production Releases (prod) + +- **Frequency**: Monthly or sprint-based +- **Scope**: Feature milestone completion, critical fixes +- **Duration**: 4+ weeks standard support +- **Deployment**: Production environment (customer-facing) +- **Who**: Product owner approves, DevOps deploys + +--- + +## πŸ”„ Product Dependency & Deployment Order + +### Critical Path (for synchronized releases) + +Deploy in this order: + +1. **DataConnect Schema** (if schema changed) + - Deploy schema changes first + - All APIs depend on schema availability + +2. **Backend Services** (parallel OK) + - Command API + - Core API + - Both can deploy simultaneously + +3. **Web Dashboard** + - Can deploy once backend ready + - Test API endpoints stable + +4. **Mobile Apps** (parallel OK) + - Staff Mobile + - Client Mobile + - Both can deploy simultaneously, independent of web + +### Independent Releases + +Products **can release independently** if: +- No backend schema changes +- No breaking API changes +- No data migrations required + +Example: Staff Mobile can release UI improvements without web/backend changes. + +--- + +## πŸ“ CHANGELOG Management + +### Location & Structure + +Each major product maintains its own CHANGELOG: + +``` +apps/mobile/packages/features/staff/*/CHANGELOG.md +apps/mobile/packages/features/client/*/CHANGELOG.md +apps/web/CHANGELOG.md +backend/command-api/CHANGELOG.md +backend/core-api/CHANGELOG.md +CHANGELOG.md (root - high-level overview) +``` + +### Format + +```markdown +| Date | Version | Change | +|------|---------|--------| +| 2026-03-05 | 0.1.0 | Initial release - [feature list] | +``` + +### What to Track + +- Features added +- Bugs fixed +- Breaking changes (clearly marked ⚠️) +- Dependencies upgraded +- Migration steps (if applicable) + +--- + +## βœ… Release Checklist + +### Pre-Release (48 hours before) + +- [ ] All PRs merged to main +- [ ] Code review complete +- [ ] All tests passing (unit, integration, E2E) +- [ ] No lint/type errors +- [ ] Mobile builds succeed (CodeMagic) +- [ ] Performance benchmarks acceptable +- [ ] Security scan completed +- [ ] CHANGELOG.md updated with all changes +- [ ] Documentation updated +- [ ] Team notified of pending release + +### Release Day + +- [ ] Update version numbers in all relevant files +- [ ] Update CHANGELOG with date +- [ ] Git commit: `git commit -m "chore: bump version to X.Y.Z"` +- [ ] Git push changes to main +- [ ] Create git tag: `git tag -a /-v -m "Release message"` +- [ ] Push tags: `git push origin ` +- [ ] Deploy to target environment +- [ ] Smoke tests pass +- [ ] Create GitHub Release page +- [ ] Notify stakeholders + +### Post-Release (24 hours) + +- [ ] Monitor error logs +- [ ] Verify all features work end-to-end +- [ ] Performance is acceptable +- [ ] No regressions reported +- [ ] Users updated if needed +- [ ] Document any issues + +--- + +## πŸ” Protected Tags + +### Branch Protection Rules + +**Production tags require approval:** + +- Tag pattern: `*/prod-v*` +- Require pull request review (1+ approval) +- Require status checks to pass +- Prevent force pushes +- Disable deletions + +**Staging tags recommended:** + +- Tag pattern: `*/stage-v*` +- Consider: Require at least 1 approval +- Status checks should pass + +**Dev tags open:** + +- Tag pattern: `*/dev-v*` +- No restrictions +- Allow fast iteration + +--- + +## 🚨 Rollback Procedures + +### For Production Issues + +**If critical issue detected:** + +1. **Identify** the product and issue +2. **Assess** impact and severity +3. **Decide** rollback vs hotfix + - Rollback: Undo entire release + - Hotfix: Fix and re-release (see HOTFIX_PROCESS.md) +4. **Execute** rollback: + ```bash + # Revert commit + git revert -m 1 + git push origin main + + # Or switch traffic back to previous version + # (depends on deployment infrastructure) + ``` +5. **Communicate** with users +6. **Plan** hotfix or next release + +### Time Windows + +- **Awareness**: 15-30 minutes (monitoring) +- **Decision**: 15-30 minutes (severity assessment) +- **Execution**: 15-60 minutes (rollback deployment) +- **Verification**: 30-60 minutes (smoke tests) +- **Communication**: Immediate + 24h updates + +**Total**: 2-4 hours from detection to stable state + +--- + +## πŸ“Š Release Templates & Tools + +### Git Commands + +```bash +# Create tag +git tag -a krow-withus-worker-mobile/dev-v0.1.0 \ + -m "Staff Mobile v0.1.0 - Feature X" + +# Push tag +git push origin krow-withus-worker-mobile/dev-v0.1.0 + +# View tags for product +git tag -l "krow-withus-worker-mobile/*" --sort=-version:refname + +# See what's in a tag +git show krow-withus-worker-mobile/dev-v0.1.0 + +# Delete tag (if mistake) +git tag -d krow-withus-worker-mobile/dev-v0.1.0 +git push origin --delete krow-withus-worker-mobile/dev-v0.1.0 +``` + +### GitHub Release Template + +```markdown +# Krow With Us - Worker Mobile - DEV - v0.1.0 + +**Release Date**: [Date] +**Environment**: Development + +## What's New + +### ✨ Features +- Feature 1 description +- Feature 2 description + +### πŸ”§ Improvements +- Improvement 1 +- Improvement 2 + +### πŸ› Bug Fixes +- Bug fix 1 +- Bug fix 2 + +## Dependencies + +Requires: +- Backend API v0.1.0 or higher +- DataConnect schema v0.3.0 (if updated) + +## Installation + +[Download links & instructions] + +## Known Issues + +- Issue 1: [desc] (Workaround: ...) + +## Support + +contact: support@krow-workforce.com +``` + +--- + +## πŸ”„ Hotfix Releases + +See [HOTFIX_PROCESS.md](./HOTFIX_PROCESS.md) for emergency procedures. + +Quick summary: +1. Branch from production tag +2. Fix the issue +3. Bump PATCH version only +4. Test and deploy immediately +5. Create hotfix tag + +--- + +## πŸ“± Mobile-Specific Release Process + +See [MOBILE_RELEASE_PLAN.md](./MOBILE_RELEASE_PLAN.md) for detailed mobile app process including: +- Staff Mobile vs Client Mobile differences +- Build number management +- CodeMagic integration +- App store distribution +- CHANGELOG per app + +--- + +## 🎯 Release Coordination + +### Single Product Release + +1. Update version files +2. Update CHANGELOG +3. Commit & push +4. Create tag +5. Deploy +6. Create GitHub Release + +**Time**: 30-45 minutes (excluding testing) + +### Multi-Product Release (e.g., v1.0.0) + +**Pre-release phase** (1 week before): +- Code freeze announced +- QA testing begins +- No new features merged + +**Release phase** (2-3 days): +- Staging release (all products) +- QA validation +- Product owner sign-off + +**Production phase** (1 day): +- Deploy in dependency order +- Smoke tests each product +- Monitor 24 hours +- User communication + +**Time**: 5-7 days total, 4 hours active deployment + +--- + +## πŸ“ž Roles & Responsibilities + +| Role | Responsibility | +|------|-----------------| +| **Developer** | Keep code release-ready, update versions | +| **QA** | Test staging releases, validate prod | +| **Release Engineer** | Create tags, manage deployment, monitor | +| **Product Owner** | Approve releases, communicate timeline | +| **DevOps** | Infrastructure ready, deployment scripts | + +--- + +## πŸ“Š Success Metrics + +Track these per release: + +- **Lead Time**: Time from code commit to production +- **Deployment Frequency**: How often you release +- **Change Failure Rate**: % of releases needing rollback +- **Time to Recovery**: Time to fix production issues +- **User Adoption**: % of users on latest version + +--- + +## πŸ“š Related Documentation + +- [MOBILE_RELEASE_PLAN.md](./MOBILE_RELEASE_PLAN.md) - Mobile app releases +- [HOTFIX_PROCESS.md](./HOTFIX_PROCESS.md) - Emergency procedures +- [../../RELEASE_STRATEGY.md](../../RELEASE_STRATEGY.md) - Original detailed guide +- [../../CHANGELOG.md](../../CHANGELOG.md) - Root version history + +--- + +## βœ… Implementation Status + +- βœ… Versioning strategy: SemVer +- βœ… Environments: dev, stage, prod +- βœ… Tag naming: Product-specific with brand prefix +- βœ… Product dependencies: Defined +- βœ… Release cadence: 3 levels +- ⏳ GitHub Actions: To be set up +- ⏳ Deployment automation: To be set up + +--- + +**Next Step**: Review [MOBILE_RELEASE_PLAN.md](./MOBILE_RELEASE_PLAN.md) for app-specific process. + From 7be3ff5bea26f8e9fae3a2b17de314f7ccad4c92 Mon Sep 17 00:00:00 2001 From: Achintha Isuru Date: Thu, 5 Mar 2026 11:10:03 -0500 Subject: [PATCH 02/15] docs(mobile): add M3 milestone CHANGELOGs for staff and client apps --- apps/mobile/apps/client_app/CHANGELOG.md | 110 +++++++++++++++++++++++ apps/mobile/apps/staff_app/CHANGELOG.md | 74 +++++++++++++++ 2 files changed, 184 insertions(+) create mode 100644 apps/mobile/apps/client_app/CHANGELOG.md create mode 100644 apps/mobile/apps/staff_app/CHANGELOG.md diff --git a/apps/mobile/apps/client_app/CHANGELOG.md b/apps/mobile/apps/client_app/CHANGELOG.md new file mode 100644 index 00000000..6388273c --- /dev/null +++ b/apps/mobile/apps/client_app/CHANGELOG.md @@ -0,0 +1,110 @@ +# Client Mobile App - Change Log + +## [0.0.1-M3] - Milestone 3 - 2026-02-15 + +### Added - Authentication & Onboarding +- Business email and password authentication +- Client account registration +- Business onboarding flow +- Company information setup + +### Added - Home Dashboard +- Welcome screen with business name +- Coverage statistics for today: + - Coverage percentage + - Workers checked in vs needed + - Open positions count +- Late workers alerts with visual indicators +- Today's estimated labor cost +- Upcoming shifts section +- Quick action buttons: + - RAPID (urgent same-day coverage) + - Create Order + - Hubs management + +### Added - Hub Management +- Hubs page accessible from settings +- Hub creation flow: + - Hub name input + - Address autocomplete with Google Maps Places API + - Hub creation confirmation +- Hubs list view showing all created hubs +- Hub card display with name, address, and tag ID + +### Added - Order Creation +- Orders tab in bottom navigation +- "+ Post" button to create new orders +- Order type selection screen: + - One-Time orders (implemented) + - RAPID orders (placeholder) + - Recurring orders (planned) + - Permanent orders (planned) +- One-Time Order creation form: + - Order name + - Date picker + - Hub selection + - Position management: + - Role selection + - Worker count + - Start/end time + - Shift duration calculation + - Cost estimation +- Order creation confirmation + +### Added - Order Management +- Orders list view with: + - Order cards showing date, location, time + - Worker count (filled/needed) + - Coverage percentage bar + - Status indicators (OPEN, FILLED, IN PROGRESS) +- Order details view: + - Event name and location + - Roles and worker requirements + - Clock in/out times + - Estimated cost + - Coverage percentage + - Map integration with directions + +### Added - Coverage Monitoring +- Coverage tab in bottom navigation +- Real-time worker status dashboard: + - Checked In (green indicator) + - En Route (yellow indicator) + - Late (red indicator) + - Not Arrived status +- Color-coded status badges +- Worker information cards +- Active shift monitoring + +### Added - Navigation +- Bottom navigation bar with tabs: + - Coverage + - Billing + - Home + - Orders + - Reports +- Settings menu accessible from home screen +- Back navigation handling + +### Added - Settings +- Settings page with options: + - Hubs management + - Profile editing + - Notifications preferences + - Log out + +### Technical Features +- Firebase authentication integration +- Data Connect backend integration +- Google Maps Places API for address autocomplete +- Real-time worker status tracking +- Cost calculation engine +- Coverage percentage calculations + +### Known Limitations +- Orders require hub assignment +- Currently supports one-time orders only +- Order approval flow not yet implemented +- RAPID, Recurring, and Permanent order types are placeholders + +--- diff --git a/apps/mobile/apps/staff_app/CHANGELOG.md b/apps/mobile/apps/staff_app/CHANGELOG.md new file mode 100644 index 00000000..8d4c26e9 --- /dev/null +++ b/apps/mobile/apps/staff_app/CHANGELOG.md @@ -0,0 +1,74 @@ +# Staff Mobile App - Change Log + +## [0.0.1-M3] - Milestone 3 - 2026-02-15 + +### Added - Authentication & Onboarding +- Phone number authentication with OTP verification +- Staff onboarding flow with profile setup +- Personal information collection (name, bio, languages) +- Preferred work locations selection +- Skills and industry selection + +### Added - Home Dashboard +- Welcome screen with personalized greeting +- Today's shifts section showing confirmed shifts +- Tomorrow's shifts preview +- Recommended shifts section based on profile +- Quick action buttons (Find Shifts, Availability, Messages, Earnings) + +### Added - Shift Management +- Find Shifts functionality to discover available work +- Shift details view showing: + - Business name and location + - Hourly rate and estimated earnings + - Date, start time, end time + - Job requirements + - Map integration with directions +- Shift booking/application process +- Booking confirmation dialog +- My Shifts view with week-by-week navigation +- Color-coded shift status (Confirmed, Pending, Completed) + +### Added - Clock In/Out +- Clock In page with slider interaction +- Clock Out page with slider interaction +- Automatic timestamp recording +- Shift status updates upon clock in/out +- Visual status indicators (green for checked in) + +### Added - Profile Management +- Profile tab with personal information +- Emergency Contact management: + - Contact name + - Relationship + - Phone number +- Bank Account linking for direct deposit +- Tax Forms section: + - W-4 form access + - I-9 form access +- Time Card view: + - Historical shift records + - Hours worked tracking + - Earnings history + +### Added - Navigation +- Bottom navigation bar with 5 tabs: + - Shifts + - Payments + - Home + - Clock In + - Profile +- Tab bar hiding on specific pages + +### Technical Features +- Firebase authentication integration +- Data Connect backend integration +- Google Maps integration for locations +- Phone verification system +- OTP code handling + +### Known Limitations +- Newly created orders don't appear immediately in Find Shifts (requires vendor approval) +- Limited to one-time order types in this milestone + +--- From e6b0a061ba97cce4efe6e4aa2433c269b06b8c4a Mon Sep 17 00:00:00 2001 From: Achintha Isuru Date: Thu, 5 Mar 2026 11:11:15 -0500 Subject: [PATCH 03/15] docs(mobile): add M4 milestone features to staff and client app CHANGELOGs --- apps/mobile/apps/client_app/CHANGELOG.md | 81 ++++++++++++++++++++++++ apps/mobile/apps/staff_app/CHANGELOG.md | 58 +++++++++++++++++ 2 files changed, 139 insertions(+) diff --git a/apps/mobile/apps/client_app/CHANGELOG.md b/apps/mobile/apps/client_app/CHANGELOG.md index 6388273c..0099ffbe 100644 --- a/apps/mobile/apps/client_app/CHANGELOG.md +++ b/apps/mobile/apps/client_app/CHANGELOG.md @@ -108,3 +108,84 @@ - RAPID, Recurring, and Permanent order types are placeholders --- + +## [0.0.2-M4] - Milestone 4 - 2026-03-05 + +### Added - Enhanced Authentication & Session Management +- Authentication session persistence across app restarts +- Automatic login with valid session tokens +- Improved user experience with seamless session handling + +### Added - RAPID Order Creation (AI-Powered) +- Voice input for order creation +- Text input for order description +- AI parsing to generate order drafts +- Same-day order support +- Populated order form matching one-time order structure +- Edit AI-generated order before submission +- Quick order creation workflow + +### Added - Recurring Order Support +- Recurring order creation flow +- Schedule configuration interface +- Recurring patterns (daily, weekly, custom) +- Recurring order management + +### Added - Permanent Order Support +- Permanent order creation flow +- Long-term position setup +- Permanent order management + +### Added - Enhanced Order Management +- Hide edit icon for past or completed orders +- Updated Reorder modal supporting all order types: + - One-Time reorder + - RAPID reorder + - Recurring reorder + - Permanent reorder +- Reorder functionality with order type awareness + +### Added - Comprehensive Reports System +- Reports page with AI-powered insights +- Three AI-generated insights on reports landing page +- Six report types: + 1. **Daily Ops Report**: Daily operational metrics and statistics + 2. **Spend Report**: Labor cost analysis and spend tracking + 3. **Coverage Report**: Shift coverage analytics and trends + 4. **No-Show Report**: Worker attendance and no-show tracking + 5. **Performance Report**: Worker performance metrics and ratings + 6. *(Reserved for future report type)* + +### Added - Hub Management Enhancements +- Dedicated hub details interface +- Detailed hub information view +- Hub editing page (separate interface) +- Enhanced hub navigation + +### Added - Home Dashboard Enhancements +- Reorder quick action button +- Insights quick action button +- Direct access to AI insights from home + +### Improved - User Experience +- Better order type selection flow +- Enhanced order creation UX across all types +- Improved reports navigation +- Better hub management interface + +### Technical Features +- iOS deployment support enabled +- Backend transaction support for order creation +- Order validation (minimum hours check) +- Shift creation validation +- 24-hour cancellation policy enforcement +- Enhanced backend reporting APIs +- AI insights generation system + +### Known Limitations +- RAPID order parsing requires clear voice/text input +- AI insights require sufficient historical data +- Reports may have limited data in early usage +- PDF export for reports not yet implemented + +--- diff --git a/apps/mobile/apps/staff_app/CHANGELOG.md b/apps/mobile/apps/staff_app/CHANGELOG.md index 8d4c26e9..24e6fe39 100644 --- a/apps/mobile/apps/staff_app/CHANGELOG.md +++ b/apps/mobile/apps/staff_app/CHANGELOG.md @@ -72,3 +72,61 @@ - Limited to one-time order types in this milestone --- + +## [0.0.2-M4] - Milestone 4 - 2026-03-05 + +### Added - Enhanced Authentication & Session Management +- Authentication session persistence across app restarts +- Automatic login with valid session tokens +- Improved user experience with seamless session handling + +### Added - Enhanced Shift Details +- Google Maps location display in shift details view +- Interactive map showing shift location +- Directions integration +- Shift requirements section showing: + - Required attire items (MUST HAVE) + - Preferred attire items (NICE TO HAVE) + - Other shift-specific requirements + +### Added - Attire Management +- Dedicated Attire screen in profile +- Upload attire images for verification +- MUST HAVE attire items list +- NICE TO HAVE attire items list +- Attire photo gallery in profile +- Submit attire for review workflow + +### Added - Profile Enhancements +- FAQ (Frequently Asked Questions) screen +- Privacy and Security settings screen: + - Profile visibility toggle ("Hide account from business") + - Terms of Service document access + - Privacy Policy document access +- Preferred locations edit screen +- Separate page for managing preferred work locations + +### Added - Profile Completion Gating +- Navigation restrictions for incomplete profiles +- Only Home and Profile tabs accessible until profile is complete +- Profile completion checklist +- Guided onboarding completion flow + +### Improved - User Experience +- Enhanced shift details UI with better information hierarchy +- Improved profile section organization +- Better navigation flow for profile completion + +### Technical Features +- iOS deployment support enabled +- Enhanced backend validation for shift acceptance +- Overlapping shift prevention +- Improved session management +- Document upload and storage integration + +### Known Limitations +- Cannot accept overlapping shifts +- Shifts require manual confirmation in some cases +- Attire verification requires manual client approval + +--- From 889d48144c85746ea1ee488a8d84f51707568bdf Mon Sep 17 00:00:00 2001 From: Achintha Isuru Date: Thu, 5 Mar 2026 11:15:05 -0500 Subject: [PATCH 04/15] docs(mobile): move CHANGELOGs to correct app directories (staff and client) --- apps/mobile/apps/{client_app => client}/CHANGELOG.md | 0 apps/mobile/apps/{staff_app => staff}/CHANGELOG.md | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename apps/mobile/apps/{client_app => client}/CHANGELOG.md (100%) rename apps/mobile/apps/{staff_app => staff}/CHANGELOG.md (100%) diff --git a/apps/mobile/apps/client_app/CHANGELOG.md b/apps/mobile/apps/client/CHANGELOG.md similarity index 100% rename from apps/mobile/apps/client_app/CHANGELOG.md rename to apps/mobile/apps/client/CHANGELOG.md diff --git a/apps/mobile/apps/staff_app/CHANGELOG.md b/apps/mobile/apps/staff/CHANGELOG.md similarity index 100% rename from apps/mobile/apps/staff_app/CHANGELOG.md rename to apps/mobile/apps/staff/CHANGELOG.md From 6b26a7214445979ee6683abad75c06632d323482 Mon Sep 17 00:00:00 2001 From: Achintha Isuru Date: Thu, 5 Mar 2026 11:16:52 -0500 Subject: [PATCH 05/15] feat(mobile): add localization support for Spanish language in staff app --- apps/mobile/apps/staff/CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/apps/mobile/apps/staff/CHANGELOG.md b/apps/mobile/apps/staff/CHANGELOG.md index 24e6fe39..7f013019 100644 --- a/apps/mobile/apps/staff/CHANGELOG.md +++ b/apps/mobile/apps/staff/CHANGELOG.md @@ -105,6 +105,7 @@ - Privacy Policy document access - Preferred locations edit screen - Separate page for managing preferred work locations +- Localization support for Spanish language ### Added - Profile Completion Gating - Navigation restrictions for incomplete profiles From c06e14e66803326e1ee797fb2d0d732bd1a81305 Mon Sep 17 00:00:00 2001 From: Achintha Isuru Date: Thu, 5 Mar 2026 11:21:43 -0500 Subject: [PATCH 06/15] docs(mobile): update M4 version to 0.0.1-M4 (keeping same base version) --- apps/mobile/apps/client/CHANGELOG.md | 2 +- apps/mobile/apps/staff/CHANGELOG.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/apps/mobile/apps/client/CHANGELOG.md b/apps/mobile/apps/client/CHANGELOG.md index 0099ffbe..cf933393 100644 --- a/apps/mobile/apps/client/CHANGELOG.md +++ b/apps/mobile/apps/client/CHANGELOG.md @@ -109,7 +109,7 @@ --- -## [0.0.2-M4] - Milestone 4 - 2026-03-05 +## [0.0.1-M4] - Milestone 4 - 2026-03-05 ### Added - Enhanced Authentication & Session Management - Authentication session persistence across app restarts diff --git a/apps/mobile/apps/staff/CHANGELOG.md b/apps/mobile/apps/staff/CHANGELOG.md index 7f013019..32661a82 100644 --- a/apps/mobile/apps/staff/CHANGELOG.md +++ b/apps/mobile/apps/staff/CHANGELOG.md @@ -73,7 +73,7 @@ --- -## [0.0.2-M4] - Milestone 4 - 2026-03-05 +## [0.0.1-M4] - Milestone 4 - 2026-03-05 ### Added - Enhanced Authentication & Session Management - Authentication session persistence across app restarts From f771bca72ac2c3b8aca2a7538d85677451c44e05 Mon Sep 17 00:00:00 2001 From: Achintha Isuru Date: Thu, 5 Mar 2026 11:34:00 -0500 Subject: [PATCH 07/15] docs(mobile): enhance CHANGELOGs with comprehensive M4 features from git history - Add Documents & Certificates management features - Include Camera/gallery support for uploads - Add Benefits overview section - Expand Attire management with verification states - Include RAPID order audio recording and transcription - Add Hub manager assignment and Cost center features - Include session management improvements - Add navigation enhancements and bug fixes - Document Core API services integration - Include all user-facing features from milestone issues --- apps/mobile/apps/client/CHANGELOG.md | 52 +++++++++++++++++++-- apps/mobile/apps/staff/CHANGELOG.md | 67 ++++++++++++++++++++++++++-- 2 files changed, 112 insertions(+), 7 deletions(-) diff --git a/apps/mobile/apps/client/CHANGELOG.md b/apps/mobile/apps/client/CHANGELOG.md index cf933393..7042b1e2 100644 --- a/apps/mobile/apps/client/CHANGELOG.md +++ b/apps/mobile/apps/client/CHANGELOG.md @@ -117,13 +117,18 @@ - Improved user experience with seamless session handling ### Added - RAPID Order Creation (AI-Powered) -- Voice input for order creation +- Voice input for order creation with audio recording - Text input for order description -- AI parsing to generate order drafts -- Same-day order support +- Multi-platform audio recording support (iOS/Android) +- AI transcription service for voice-to-text conversion +- AI parsing to generate order drafts from natural language +- Same-day order support for urgent coverage needs - Populated order form matching one-time order structure - Edit AI-generated order before submission - Quick order creation workflow +- Audio file upload for transcription +- RAPID order verification page with refinements +- Hub and role matching for order creation ### Added - Recurring Order Support - Recurring order creation flow @@ -144,6 +149,14 @@ - Recurring reorder - Permanent reorder - Reorder functionality with order type awareness +- Hub manager assignment to orders +- Cost center entity linking to hubs +- Completion review UI with: + - Actions summary + - Amount display + - Info sections + - Worker listing +- Invoice management improvements ### Added - Comprehensive Reports System - Reports page with AI-powered insights @@ -164,14 +177,36 @@ ### Added - Home Dashboard Enhancements - Reorder quick action button -- Insights quick action button +### Added - Home Dashboard Enhancements +- Reorder quick action button for fast order duplication +- Insights quick action button for AI analytics - Direct access to AI insights from home +- Refactored home widgets with SectionLayout: + - Today's shifts section with titles + - Tomorrow's shifts section + - Coverage widget improvements + - Live activity widget enhancements + - Spending widget updates +- Full-width dividers for better visual separation +- Improved dashboard widget organization ### Improved - User Experience - Better order type selection flow - Enhanced order creation UX across all types - Improved reports navigation - Better hub management interface +- Bottom navigation bar show/hide based on route changes +- Enhanced navigation robustness with error handling +- Improved invoice page layout with reordered titles +- Session management improvements with proper role validation +- Enhanced settings page navigation flow +- Better amount widget styling in completion review + +### Fixed +- Client app crash issues resolved +- Shift booking status inconsistencies fixed +- Session navigation errors corrected +- Formatting and code clarity improvements across codebase ### Technical Features - iOS deployment support enabled @@ -181,6 +216,15 @@ - 24-hour cancellation policy enforcement - Enhanced backend reporting APIs - AI insights generation system +- Core API integration: + - RAPID order transcription endpoints + - Order parsing services + - File upload with signed URLs + - LLM services +- ApiService with Dio for standardized API requests +- DataConnectService integration across all repositories +- Enhanced session management with SessionListener +- Role-based session handling ### Known Limitations - RAPID order parsing requires clear voice/text input diff --git a/apps/mobile/apps/staff/CHANGELOG.md b/apps/mobile/apps/staff/CHANGELOG.md index 32661a82..71fb9cb1 100644 --- a/apps/mobile/apps/staff/CHANGELOG.md +++ b/apps/mobile/apps/staff/CHANGELOG.md @@ -91,11 +91,33 @@ ### Added - Attire Management - Dedicated Attire screen in profile +- Camera and gallery support for attire photo capture +- Local image preview before submission - Upload attire images for verification - MUST HAVE attire items list - NICE TO HAVE attire items list - Attire photo gallery in profile - Submit attire for review workflow +- Attire verification status tracking (Pending, Approved, Rejected) +- Attestation checkbox for attire accuracy confirmation +- Filtered attire items based on requirements + +### Added - Documents & Certificates Management +- Documents section in profile with verification status tracking +- Upload documents (ID, licenses, etc.) with: + - Camera or gallery selection + - File type validation + - Upload progress tracking + - Verification metadata +- Certificates management: + - Upload certificates with expiry dates + - Certificate number field + - Certificate type selection + - View existing certificates + - Delete certificates + - Verification status (Not Verified, Verified, Expired) +- Mandatory document flagging +- Document verification workflow ### Added - Profile Enhancements - FAQ (Frequently Asked Questions) screen @@ -103,9 +125,24 @@ - Profile visibility toggle ("Hide account from business") - Terms of Service document access - Privacy Policy document access -- Preferred locations edit screen -- Separate page for managing preferred work locations -- Localization support for Spanish language +- Preferred locations management: + - Dedicated edit screen + - Location search functionality + - Display selected locations +- Language selection interface: + - Spanish language support + - Success feedback on language change + - Persistent language preference +- Benefits overview section: + - Benefits listing with circular progress indicators + - Benefits dashboard integration +- Profile completion tracking for: + - Personal information + - Emergency contacts + - Experience + - Attire + - Documents + - Certificates ### Added - Profile Completion Gating - Navigation restrictions for incomplete profiles @@ -117,6 +154,24 @@ - Enhanced shift details UI with better information hierarchy - Improved profile section organization - Better navigation flow for profile completion +- UiEmptyState widgets for better empty state handling: + - Bank account page empty state + - Home page when no shifts available +- Improved onboarding flow with refactored experience and personal info pages +- Enhanced emergency contact screen with info banner +- Refactored profile header with profile level badge ("KROWER I") +- Benefits card components with improved styling +- Bottom navigation bar show/hide based on route +- Tax forms page with progress overview +- Improved notice and file type banners for uploads +- Enhanced navigation robustness with proper error handling +- Immediate ID token refresh after sign-in to prevent unauthenticated requests + +### Fixed +- Profile completion status now updates correctly for emergency contacts +- Session handling improved to prevent data loss +- Navigation errors redirect to appropriate home page +- Locale synchronization by reloading from persistent storage after change ### Technical Features - iOS deployment support enabled @@ -124,6 +179,12 @@ - Overlapping shift prevention - Improved session management - Document upload and storage integration +- Signed URL generation for file uploads +- Camera and gallery native device access +- File visibility controls (public/private) +- Core API services integration (verification, file upload, LLM) +- ApiService with Dio for standardized API requests +- Device services abstraction layer ### Known Limitations - Cannot accept overlapping shifts From 89dd9fe723d8821626c2983a00fe8adeca9e9db7 Mon Sep 17 00:00:00 2001 From: Achintha Isuru Date: Thu, 5 Mar 2026 11:38:36 -0500 Subject: [PATCH 08/15] docs(mobile): remove placeholder entries for RAPID and recurring orders in CHANGELOGs --- apps/mobile/apps/client/CHANGELOG.md | 5 ----- apps/mobile/apps/staff/CHANGELOG.md | 1 - 2 files changed, 6 deletions(-) diff --git a/apps/mobile/apps/client/CHANGELOG.md b/apps/mobile/apps/client/CHANGELOG.md index 7042b1e2..aab9e184 100644 --- a/apps/mobile/apps/client/CHANGELOG.md +++ b/apps/mobile/apps/client/CHANGELOG.md @@ -18,7 +18,6 @@ - Today's estimated labor cost - Upcoming shifts section - Quick action buttons: - - RAPID (urgent same-day coverage) - Create Order - Hubs management @@ -36,9 +35,6 @@ - "+ Post" button to create new orders - Order type selection screen: - One-Time orders (implemented) - - RAPID orders (placeholder) - - Recurring orders (planned) - - Permanent orders (planned) - One-Time Order creation form: - Order name - Date picker @@ -209,7 +205,6 @@ - Formatting and code clarity improvements across codebase ### Technical Features -- iOS deployment support enabled - Backend transaction support for order creation - Order validation (minimum hours check) - Shift creation validation diff --git a/apps/mobile/apps/staff/CHANGELOG.md b/apps/mobile/apps/staff/CHANGELOG.md index 71fb9cb1..0a9b9e54 100644 --- a/apps/mobile/apps/staff/CHANGELOG.md +++ b/apps/mobile/apps/staff/CHANGELOG.md @@ -174,7 +174,6 @@ - Locale synchronization by reloading from persistent storage after change ### Technical Features -- iOS deployment support enabled - Enhanced backend validation for shift acceptance - Overlapping shift prevention - Improved session management From 054852fcde7a4f8d607b31e74abd2b936f596762 Mon Sep 17 00:00:00 2001 From: Achintha Isuru Date: Thu, 5 Mar 2026 11:41:45 -0500 Subject: [PATCH 09/15] feat(ci): add GitHub Actions workflows for mobile releases and hotfixes - Add mobile-release.yml workflow: - Manual trigger with app (worker/client) and environment (dev/stage/prod) selection - Version validation (semantic versioning) - Tag creation with format: krow-withus--mobile/-vX.Y.Z - GitHub Release creation with CHANGELOG extraction - Release naming: 'Krow With Us - Worker Mobile - DEV - v0.1.0' - Pre-release support - Add mobile-hotfix.yml workflow: - Emergency production fix automation - Creates hotfix branch from production tag - Auto-increments PATCH version - Updates pubspec.yaml and CHANGELOG.md - Creates PR with hotfix instructions - Follows documented hotfix process Both workflows support staff (worker) and client mobile apps independently. Implements mobile release strategy from docs/release/ --- .github/workflows/mobile-hotfix.yml | 322 +++++++++++++++++++++++++++ .github/workflows/mobile-release.yml | 215 ++++++++++++++++++ 2 files changed, 537 insertions(+) create mode 100644 .github/workflows/mobile-hotfix.yml create mode 100644 .github/workflows/mobile-release.yml diff --git a/.github/workflows/mobile-hotfix.yml b/.github/workflows/mobile-hotfix.yml new file mode 100644 index 00000000..cd2df197 --- /dev/null +++ b/.github/workflows/mobile-hotfix.yml @@ -0,0 +1,322 @@ +name: Mobile Hotfix + +on: + workflow_dispatch: + inputs: + app: + description: 'Mobile App' + required: true + type: choice + options: + - worker + - client + production_tag: + description: 'Current Production Tag (e.g., krow-withus-worker-mobile/prod-v0.1.0)' + required: true + type: string + issue_description: + description: 'Brief issue description' + required: true + type: string + +jobs: + create-hotfix-branch: + name: 🚨 Create Hotfix Branch + runs-on: ubuntu-latest + permissions: + contents: write + pull-requests: write + + steps: + - name: πŸ“₯ Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: πŸ” Validate production tag exists + id: validate_tag + run: | + TAG="${{ github.event.inputs.production_tag }}" + + if ! git rev-parse "$TAG" >/dev/null 2>&1; then + echo "❌ Error: Production tag '$TAG' does not exist" + echo "Available tags:" + git tag -l "krow-withus-*-mobile/prod-*" | tail -10 + exit 1 + fi + + echo "βœ… Production tag exists: $TAG" + + # Extract version from tag + VERSION=$(echo "$TAG" | grep -oP 'v\K[0-9]+\.[0-9]+\.[0-9]+' || echo "") + if [ -z "$VERSION" ]; then + echo "❌ Error: Could not extract version from tag" + exit 1 + fi + + echo "current_version=${VERSION}" >> $GITHUB_OUTPUT + echo "πŸ“Œ Current production version: $VERSION" + + - name: πŸ”’ Calculate hotfix version + id: hotfix_version + run: | + CURRENT="${{ steps.validate_tag.outputs.current_version }}" + + # Split version into parts + IFS='.' read -r MAJOR MINOR PATCH <<< "$CURRENT" + + # Increment PATCH version + NEW_PATCH=$((PATCH + 1)) + HOTFIX_VERSION="${MAJOR}.${MINOR}.${NEW_PATCH}" + + echo "hotfix_version=${HOTFIX_VERSION}" >> $GITHUB_OUTPUT + echo "πŸ†• Hotfix version: $HOTFIX_VERSION" + + - name: 🌿 Generate branch name + id: branch + run: | + APP="${{ github.event.inputs.app }}" + VERSION="${{ steps.hotfix_version.outputs.hotfix_version }}" + + BRANCH_NAME="hotfix/krow-withus-${APP}-mobile-v${VERSION}" + echo "branch_name=${BRANCH_NAME}" >> $GITHUB_OUTPUT + echo "🌿 Branch to create: $BRANCH_NAME" + + - name: πŸ” Check if hotfix branch already exists + run: | + BRANCH="${{ steps.branch.outputs.branch_name }}" + + if git ls-remote --heads origin "$BRANCH" | grep -q "$BRANCH"; then + echo "❌ Error: Branch $BRANCH already exists" + exit 1 + fi + + echo "βœ… Branch does not exist, proceeding..." + + - name: 🌿 Create hotfix branch from production tag + run: | + TAG="${{ github.event.inputs.production_tag }}" + BRANCH="${{ steps.branch.outputs.branch_name }}" + + git config user.name "github-actions[bot]" + git config user.email "github-actions[bot]@users.noreply.github.com" + + # Checkout the production tag + git checkout "$TAG" + + # Create new branch + git checkout -b "$BRANCH" + + echo "βœ… Created branch $BRANCH from tag $TAG" + + - name: πŸ“ Update version files + id: update_versions + run: | + APP="${{ github.event.inputs.app }}" + HOTFIX_VERSION="${{ steps.hotfix_version.outputs.hotfix_version }}" + + if [ "$APP" = "worker" ]; then + PUBSPEC_PATH="apps/mobile/apps/staff/pubspec.yaml" + CHANGELOG_PATH="apps/mobile/apps/staff/CHANGELOG.md" + APP_NAME="Staff Mobile App" + else + PUBSPEC_PATH="apps/mobile/apps/client/pubspec.yaml" + CHANGELOG_PATH="apps/mobile/apps/client/CHANGELOG.md" + APP_NAME="Client Mobile App" + fi + + # Update pubspec.yaml version + if [ -f "$PUBSPEC_PATH" ]; then + # Extract current version and build number + CURRENT_VERSION_LINE=$(grep "^version:" "$PUBSPEC_PATH") + CURRENT_BUILD=$(echo "$CURRENT_VERSION_LINE" | grep -oP '\+\K[0-9]+' || echo "1") + NEW_BUILD=$((CURRENT_BUILD + 1)) + + # Update version line + sed -i "s/^version:.*/version: ${HOTFIX_VERSION}+${NEW_BUILD}/" "$PUBSPEC_PATH" + + echo "βœ… Updated $PUBSPEC_PATH to ${HOTFIX_VERSION}+${NEW_BUILD}" + echo "updated_files=true" >> $GITHUB_OUTPUT + else + echo "⚠️ Warning: $PUBSPEC_PATH not found" + echo "updated_files=false" >> $GITHUB_OUTPUT + fi + + - name: πŸ“‹ Add CHANGELOG entry + run: | + APP="${{ github.event.inputs.app }}" + HOTFIX_VERSION="${{ steps.hotfix_version.outputs.hotfix_version }}" + ISSUE="${{ github.event.inputs.issue_description }}" + + if [ "$APP" = "worker" ]; then + CHANGELOG_PATH="apps/mobile/apps/staff/CHANGELOG.md" + APP_NAME="Staff Mobile App" + else + CHANGELOG_PATH="apps/mobile/apps/client/CHANGELOG.md" + APP_NAME="Client Mobile App" + fi + + if [ -f "$CHANGELOG_PATH" ]; then + DATE=$(date +%Y-%m-%d) + + # Create hotfix entry + HOTFIX_ENTRY="## [${HOTFIX_VERSION}] - ${DATE} - HOTFIX + +### Fixed +- ${ISSUE} + +--- + +" + + # Insert after the first line (title) + sed -i "1 a\\ +\\ +$HOTFIX_ENTRY" "$CHANGELOG_PATH" + + echo "βœ… Added CHANGELOG entry for hotfix $HOTFIX_VERSION" + else + echo "⚠️ Warning: $CHANGELOG_PATH not found" + fi + + - name: πŸ’Ύ Commit version changes + run: | + HOTFIX_VERSION="${{ steps.hotfix_version.outputs.hotfix_version }}" + ISSUE="${{ github.event.inputs.issue_description }}" + + git add -A + git commit -m "chore: prepare hotfix v${HOTFIX_VERSION} + +HOTFIX: ${ISSUE} + +- Bump version to ${HOTFIX_VERSION} +- Add CHANGELOG entry +- Ready for bug fix commits + +From production tag: ${{ github.event.inputs.production_tag }}" + + echo "βœ… Committed version changes" + + - name: πŸš€ Push hotfix branch + run: | + BRANCH="${{ steps.branch.outputs.branch_name }}" + + git push origin "$BRANCH" + + echo "βœ… Pushed branch: $BRANCH" + + - name: πŸ“„ Create Pull Request + id: create_pr + env: + GH_TOKEN: ${{ github.token }} + run: | + BRANCH="${{ steps.branch.outputs.branch_name }}" + HOTFIX_VERSION="${{ steps.hotfix_version.outputs.hotfix_version }}" + ISSUE="${{ github.event.inputs.issue_description }}" + APP="${{ github.event.inputs.app }}" + + if [ "$APP" = "worker" ]; then + APP_DISPLAY="Worker Mobile" + else + APP_DISPLAY="Client Mobile" + fi + + PR_TITLE="🚨 HOTFIX: ${APP_DISPLAY} v${HOTFIX_VERSION} - ${ISSUE}" + + PR_BODY="## 🚨 HOTFIX - URGENT PRODUCTION FIX + +**App:** ${APP_DISPLAY} +**Version:** ${HOTFIX_VERSION} +**From:** \`${{ github.event.inputs.production_tag }}\` + +### Issue +${ISSUE} + +### Impact + + +### Solution + + +### Testing + + +--- + +## ⚠️ Hotfix Process + +1. βœ… Hotfix branch created +2. ⏳ **NEXT:** Make your bug fix commits to this branch +3. ⏳ Test the fix locally +4. ⏳ Request expedited review (< 15 minutes) +5. ⏳ Merge to main and create production tag + +### To add your fix: +\`\`\`bash +git checkout $BRANCH +# Make your changes +git commit -m \"fix: [description]\" +git push origin $BRANCH +\`\`\` + +### After merging: +\`\`\`bash +# Tag and release +git checkout main +git pull origin main +git tag -a krow-withus-${APP}-mobile/prod-v${HOTFIX_VERSION} -m \"HOTFIX: ${ISSUE}\" +git push origin krow-withus-${APP}-mobile/prod-v${HOTFIX_VERSION} +\`\`\` + +--- + +**Ref:** [Hotfix Process Documentation](../docs/release/HOTFIX_PROCESS.md)" + + # Create PR + PR_URL=$(gh pr create \ + --base main \ + --head "$BRANCH" \ + --title "$PR_TITLE" \ + --body "$PR_BODY" \ + --label "hotfix,urgent,production") + + echo "pr_url=${PR_URL}" >> $GITHUB_OUTPUT + echo "βœ… Pull Request created: $PR_URL" + + - name: πŸ“Š Hotfix Summary + run: | + echo "## 🚨 Hotfix Branch Created" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "**App:** ${{ github.event.inputs.app }}" >> $GITHUB_STEP_SUMMARY + echo "**Issue:** ${{ github.event.inputs.issue_description }}" >> $GITHUB_STEP_SUMMARY + echo "**From Tag:** \`${{ github.event.inputs.production_tag }}\`" >> $GITHUB_STEP_SUMMARY + echo "**Current Version:** ${{ steps.validate_tag.outputs.current_version }}" >> $GITHUB_STEP_SUMMARY + echo "**Hotfix Version:** ${{ steps.hotfix_version.outputs.hotfix_version }}" >> $GITHUB_STEP_SUMMARY + echo "**Branch:** \`${{ steps.branch.outputs.branch_name }}\`" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "### πŸ”§ Next Steps" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "1. **Checkout the hotfix branch:**" >> $GITHUB_STEP_SUMMARY + echo " \`\`\`bash" >> $GITHUB_STEP_SUMMARY + echo " git fetch origin" >> $GITHUB_STEP_SUMMARY + echo " git checkout ${{ steps.branch.outputs.branch_name }}" >> $GITHUB_STEP_SUMMARY + echo " \`\`\`" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "2. **Make your bug fix(es)** - Keep changes minimal!" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "3. **Test locally** - Verify the fix works" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "4. **Request expedited review** - Target < 15 minutes" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "5. **Merge PR and create production tag:**" >> $GITHUB_STEP_SUMMARY + echo " \`\`\`bash" >> $GITHUB_STEP_SUMMARY + echo " git checkout main" >> $GITHUB_STEP_SUMMARY + echo " git pull origin main" >> $GITHUB_STEP_SUMMARY + echo " git tag -a krow-withus-${{ github.event.inputs.app }}-mobile/prod-v${{ steps.hotfix_version.outputs.hotfix_version }} -m \"HOTFIX: ${{ github.event.inputs.issue_description }}\"" >> $GITHUB_STEP_SUMMARY + echo " git push origin krow-withus-${{ github.event.inputs.app }}-mobile/prod-v${{ steps.hotfix_version.outputs.hotfix_version }}" >> $GITHUB_STEP_SUMMARY + echo " \`\`\`" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + + if [ -n "${{ steps.create_pr.outputs.pr_url }}" ]; then + echo "**Pull Request:** ${{ steps.create_pr.outputs.pr_url }}" >> $GITHUB_STEP_SUMMARY + fi diff --git a/.github/workflows/mobile-release.yml b/.github/workflows/mobile-release.yml new file mode 100644 index 00000000..00dba7d3 --- /dev/null +++ b/.github/workflows/mobile-release.yml @@ -0,0 +1,215 @@ +name: Mobile Release + +on: + workflow_dispatch: + inputs: + app: + description: 'Mobile App' + required: true + type: choice + options: + - worker + - client + environment: + description: 'Environment' + required: true + type: choice + options: + - dev + - stage + - prod + version: + description: 'Version (e.g., 0.1.0)' + required: true + type: string + create_github_release: + description: 'Create GitHub Release' + required: true + type: boolean + default: true + prerelease: + description: 'Mark as Pre-release' + required: false + type: boolean + default: false + +jobs: + validate-and-create-release: + name: πŸš€ Create Mobile Release + runs-on: ubuntu-latest + permissions: + contents: write + + steps: + - name: πŸ“₯ Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: πŸ” Validate version format + run: | + VERSION="${{ github.event.inputs.version }}" + if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then + echo "❌ Error: Version must be in format X.Y.Z (e.g., 0.1.0)" + exit 1 + fi + echo "βœ… Version format valid: $VERSION" + + - name: 🏷️ Generate tag name + id: tag + run: | + APP="${{ github.event.inputs.app }}" + ENV="${{ github.event.inputs.environment }}" + VERSION="${{ github.event.inputs.version }}" + + TAG_NAME="krow-withus-${APP}-mobile/${ENV}-v${VERSION}" + echo "tag_name=${TAG_NAME}" >> $GITHUB_OUTPUT + echo "πŸ“Œ Tag to create: ${TAG_NAME}" + + - name: πŸ” Check if tag already exists + run: | + TAG_NAME="${{ steps.tag.outputs.tag_name }}" + if git rev-parse "$TAG_NAME" >/dev/null 2>&1; then + echo "❌ Error: Tag $TAG_NAME already exists" + exit 1 + fi + echo "βœ… Tag does not exist, proceeding..." + + - name: πŸ“ Verify CHANGELOG exists + run: | + APP="${{ github.event.inputs.app }}" + if [ "$APP" = "worker" ]; then + CHANGELOG_PATH="apps/mobile/apps/staff/CHANGELOG.md" + else + CHANGELOG_PATH="apps/mobile/apps/client/CHANGELOG.md" + fi + + if [ ! -f "$CHANGELOG_PATH" ]; then + echo "⚠️ Warning: CHANGELOG not found at $CHANGELOG_PATH" + else + echo "βœ… CHANGELOG found at $CHANGELOG_PATH" + echo "changelog_path=${CHANGELOG_PATH}" >> $GITHUB_ENV + fi + + - name: πŸ“‹ Extract release notes from CHANGELOG + id: release_notes + run: | + APP="${{ github.event.inputs.app }}" + VERSION="${{ github.event.inputs.version }}" + + if [ "$APP" = "worker" ]; then + CHANGELOG_PATH="apps/mobile/apps/staff/CHANGELOG.md" + APP_NAME="Staff Mobile App (Worker)" + else + CHANGELOG_PATH="apps/mobile/apps/client/CHANGELOG.md" + APP_NAME="Client Mobile App" + fi + + # Try to extract release notes for this version + if [ -f "$CHANGELOG_PATH" ]; then + # Extract section for this version + NOTES=$(awk "/## \[${VERSION}\]/,/^## \[/" "$CHANGELOG_PATH" | sed '1d;$d' | sed '/^$/d') + + if [ -z "$NOTES" ]; then + NOTES="Release $VERSION for $APP_NAME + +No CHANGELOG entry found for this version. Please update the CHANGELOG manually. + +**Environment:** ${{ github.event.inputs.environment }} +**Tag:** ${{ steps.tag.outputs.tag_name }}" + else + NOTES="# $APP_NAME - Release $VERSION + +$NOTES + +--- + +**Environment:** ${{ github.event.inputs.environment }} +**Tag:** ${{ steps.tag.outputs.tag_name }}" + fi + else + NOTES="Release $VERSION for $APP_NAME + +**Environment:** ${{ github.event.inputs.environment }} +**Tag:** ${{ steps.tag.outputs.tag_name }}" + fi + + # Save to file to handle multiline + echo "$NOTES" > /tmp/release_notes.md + echo "notes_file=/tmp/release_notes.md" >> $GITHUB_OUTPUT + + - name: 🏷️ Create Git Tag + run: | + TAG_NAME="${{ steps.tag.outputs.tag_name }}" + APP="${{ github.event.inputs.app }}" + ENV="${{ github.event.inputs.environment }}" + VERSION="${{ github.event.inputs.version }}" + + git config user.name "github-actions[bot]" + git config user.email "github-actions[bot]@users.noreply.github.com" + + git tag -a "$TAG_NAME" -m "Release ${APP} mobile app ${VERSION} to ${ENV}" + git push origin "$TAG_NAME" + + echo "βœ… Tag created and pushed: $TAG_NAME" + + - name: πŸ“¦ Create GitHub Release + if: ${{ github.event.inputs.create_github_release == 'true' }} + env: + GH_TOKEN: ${{ github.token }} + run: | + TAG_NAME="${{ steps.tag.outputs.tag_name }}" + APP="${{ github.event.inputs.app }}" + ENV="${{ github.event.inputs.environment }}" + VERSION="${{ github.event.inputs.version }}" + + # Generate release title + if [ "$APP" = "worker" ]; then + APP_DISPLAY="Worker Mobile" + else + APP_DISPLAY="Client Mobile" + fi + + ENV_UPPER=$(echo "$ENV" | tr '[:lower:]' '[:upper:]') + RELEASE_NAME="Krow With Us - ${APP_DISPLAY} - ${ENV_UPPER} - v${VERSION}" + + # Create release + if [ "${{ github.event.inputs.prerelease }}" = "true" ]; then + gh release create "$TAG_NAME" \ + --title "$RELEASE_NAME" \ + --notes-file "${{ steps.release_notes.outputs.notes_file }}" \ + --prerelease + else + gh release create "$TAG_NAME" \ + --title "$RELEASE_NAME" \ + --notes-file "${{ steps.release_notes.outputs.notes_file }}" + fi + + echo "βœ… GitHub Release created: $RELEASE_NAME" + + - name: πŸ“Š Release Summary + run: | + echo "## πŸš€ Release Created Successfully" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "**App:** ${{ github.event.inputs.app }}" >> $GITHUB_STEP_SUMMARY + echo "**Environment:** ${{ github.event.inputs.environment }}" >> $GITHUB_STEP_SUMMARY + echo "**Version:** ${{ github.event.inputs.version }}" >> $GITHUB_STEP_SUMMARY + echo "**Tag:** \`${{ steps.tag.outputs.tag_name }}\`" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + + if [ "${{ github.event.inputs.app }}" = "worker" ]; then + APP_DISPLAY="Worker Mobile" + else + APP_DISPLAY="Client Mobile" + fi + ENV_UPPER=$(echo "${{ github.event.inputs.environment }}" | tr '[:lower:]' '[:upper:]') + RELEASE_NAME="Krow With Us - ${APP_DISPLAY} - ${ENV_UPPER} - v${{ github.event.inputs.version }}" + + echo "**Release Name:** $RELEASE_NAME" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "### Next Steps" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "1. Verify the tag and release on GitHub" >> $GITHUB_STEP_SUMMARY + echo "2. Trigger CodeMagic build (if configured)" >> $GITHUB_STEP_SUMMARY + echo "3. Monitor app store deployment" >> $GITHUB_STEP_SUMMARY + echo "4. Update project documentation if needed" >> $GITHUB_STEP_SUMMARY From 0e296bf83b3bbcd60cc77b04393d444fe05a4bb3 Mon Sep 17 00:00:00 2001 From: Achintha Isuru Date: Thu, 5 Mar 2026 11:49:11 -0500 Subject: [PATCH 10/15] refactor(ci): enhance mobile release workflow with emojis and extracted scripts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ✨ Enhanced mobile-release.yml workflow: - πŸ“± Added emojis to all steps for better visual feedback - πŸ”§ Version now automatically extracted from pubspec.yaml - No manual version input required - Reads from apps/mobile/apps/staff/pubspec.yaml for worker - Reads from apps/mobile/apps/client/pubspec.yaml for client - πŸ“ Removed manual version input field from workflow πŸ”¨ Created reusable shell scripts in .github/scripts/: 1. extract-version.sh - Extract version from pubspec.yaml 2. generate-tag-name.sh - Generate tag names consistently 3. extract-release-notes.sh - Extract CHANGELOG sections 4. create-release-summary.sh - Generate GitHub Step Summary with emojis Benefits: βœ… Simpler workflow - just select app and environment βœ… Single source of truth for versions (pubspec.yaml) βœ… Reusable scripts can be used in other workflows βœ… Better error messages and validation βœ… Enhanced visual feedback with emojis βœ… Cleaner workflow file (moved logic to scripts) --- .github/scripts/create-release-summary.sh | 73 +++++++++++ .github/scripts/extract-release-notes.sh | 65 ++++++++++ .github/scripts/extract-version.sh | 48 +++++++ .github/scripts/generate-tag-name.sh | 18 +++ .github/workflows/mobile-release.yml | 150 ++++++---------------- 5 files changed, 244 insertions(+), 110 deletions(-) create mode 100755 .github/scripts/create-release-summary.sh create mode 100755 .github/scripts/extract-release-notes.sh create mode 100755 .github/scripts/extract-version.sh create mode 100755 .github/scripts/generate-tag-name.sh diff --git a/.github/scripts/create-release-summary.sh b/.github/scripts/create-release-summary.sh new file mode 100755 index 00000000..9b182968 --- /dev/null +++ b/.github/scripts/create-release-summary.sh @@ -0,0 +1,73 @@ +#!/bin/bash +# Generate release summary for GitHub Actions +# Usage: ./create-release-summary.sh + +set -e + +APP=$1 +ENV=$2 +VERSION=$3 +TAG_NAME=$4 + +if [ -z "$APP" ] || [ -z "$ENV" ] || [ -z "$VERSION" ] || [ -z "$TAG_NAME" ]; then + echo "❌ Error: Missing required parameters" + echo "Usage: ./create-release-summary.sh " + exit 1 +fi + +# Determine display names +if [ "$APP" = "worker" ]; then + APP_DISPLAY="Worker Mobile" + APP_EMOJI="πŸ‘·" +else + APP_DISPLAY="Client Mobile" + APP_EMOJI="πŸ’Ό" +fi + +ENV_UPPER=$(echo "$ENV" | tr '[:lower:]' '[:upper:]') +RELEASE_NAME="Krow With Us - ${APP_DISPLAY} - ${ENV_UPPER} - v${VERSION}" + +# Environment emoji +case "$ENV" in + dev) + ENV_EMOJI="πŸ”§" + ;; + stage) + ENV_EMOJI="🎭" + ;; + prod) + ENV_EMOJI="πŸš€" + ;; + *) + ENV_EMOJI="πŸ“¦" + ;; +esac + +# Generate summary +cat << EOF >> $GITHUB_STEP_SUMMARY +## πŸŽ‰ Release Created Successfully + +### ${APP_EMOJI} Application Details +- **App:** ${APP_DISPLAY} +- **Environment:** ${ENV_EMOJI} ${ENV_UPPER} +- **Version:** \`${VERSION}\` +- **Tag:** \`${TAG_NAME}\` + +### πŸ“¦ Release Information +**Release Name:** ${RELEASE_NAME} + +### βœ… Next Steps + +1. πŸ” **Verify** the tag and release on GitHub +2. πŸ—οΈ **Trigger** CodeMagic build (if configured) +3. πŸ“± **Monitor** app store deployment +4. πŸ“š **Update** project documentation if needed +5. 🎯 **Communicate** release to stakeholders + +### πŸ”— Quick Links +- [View Tag](../../releases/tag/${TAG_NAME}) +- [Release Documentation](../../docs/release/MOBILE_RELEASE_PLAN.md) +- [CHANGELOG](../../apps/mobile/apps/${APP}/CHANGELOG.md) +EOF + +echo "βœ… Summary generated successfully" diff --git a/.github/scripts/extract-release-notes.sh b/.github/scripts/extract-release-notes.sh new file mode 100755 index 00000000..31c59f2b --- /dev/null +++ b/.github/scripts/extract-release-notes.sh @@ -0,0 +1,65 @@ +#!/bin/bash +# Extract release notes from CHANGELOG for a specific version +# Usage: ./extract-release-notes.sh + +set -e + +APP=$1 +VERSION=$2 +ENV=$3 +TAG_NAME=$4 +OUTPUT_FILE=$5 + +if [ -z "$APP" ] || [ -z "$VERSION" ] || [ -z "$ENV" ] || [ -z "$TAG_NAME" ] || [ -z "$OUTPUT_FILE" ]; then + echo "❌ Error: Missing required parameters" + echo "Usage: ./extract-release-notes.sh " + exit 1 +fi + +# Determine CHANGELOG path and app name +if [ "$APP" = "worker" ]; then + CHANGELOG_PATH="apps/mobile/apps/staff/CHANGELOG.md" + APP_NAME="Staff Mobile App (Worker)" +else + CHANGELOG_PATH="apps/mobile/apps/client/CHANGELOG.md" + APP_NAME="Client Mobile App" +fi + +# Try to extract release notes for this version +if [ -f "$CHANGELOG_PATH" ]; then + echo "πŸ“ Found CHANGELOG at $CHANGELOG_PATH" + + # Extract section for this version + # Look for ## [VERSION] and collect until next ## [ or end of file + NOTES=$(awk "/## \[${VERSION}\]/,/^## \[/" "$CHANGELOG_PATH" | sed '1d;$d' | sed '/^$/d') + + if [ -z "$NOTES" ]; then + echo "⚠️ Warning: No CHANGELOG entry found for version $VERSION" + NOTES="Release $VERSION for $APP_NAME + +⚠️ No CHANGELOG entry found for this version. Please update the CHANGELOG manually. + +**Environment:** $ENV +**Tag:** $TAG_NAME" + else + echo "βœ… Extracted release notes for version $VERSION" + NOTES="# $APP_NAME - Release $VERSION + +$NOTES + +--- + +**Environment:** $ENV +**Tag:** $TAG_NAME" + fi +else + echo "⚠️ Warning: CHANGELOG not found at $CHANGELOG_PATH" + NOTES="Release $VERSION for $APP_NAME + +**Environment:** $ENV +**Tag:** $TAG_NAME" +fi + +# Save to output file +echo "$NOTES" > "$OUTPUT_FILE" +echo "βœ… Release notes saved to $OUTPUT_FILE" diff --git a/.github/scripts/extract-version.sh b/.github/scripts/extract-version.sh new file mode 100755 index 00000000..0df25d72 --- /dev/null +++ b/.github/scripts/extract-version.sh @@ -0,0 +1,48 @@ +#!/bin/bash +# Extract version from pubspec.yaml for mobile apps +# Usage: ./extract-version.sh +# app: worker or client + +set -e + +APP=$1 + +if [ -z "$APP" ]; then + echo "❌ Error: App parameter required (worker or client)" + exit 1 +fi + +# Determine pubspec path +if [ "$APP" = "worker" ]; then + PUBSPEC_PATH="apps/mobile/apps/staff/pubspec.yaml" + APP_NAME="Staff Mobile App (Worker)" +else + PUBSPEC_PATH="apps/mobile/apps/client/pubspec.yaml" + APP_NAME="Client Mobile App" +fi + +# Check if pubspec exists +if [ ! -f "$PUBSPEC_PATH" ]; then + echo "❌ Error: pubspec.yaml not found at $PUBSPEC_PATH" + exit 1 +fi + +# Extract version (format: X.Y.Z+buildNumber) +VERSION_LINE=$(grep "^version:" "$PUBSPEC_PATH") +if [ -z "$VERSION_LINE" ]; then + echo "❌ Error: Could not find version in $PUBSPEC_PATH" + exit 1 +fi + +# Extract just the semantic version (before the +) +VERSION=$(echo "$VERSION_LINE" | sed 's/version: *//' | sed 's/+.*//' | tr -d ' ') + +# Validate version format +if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then + echo "❌ Error: Invalid version format in pubspec.yaml: $VERSION" + echo "Expected format: X.Y.Z (e.g., 0.1.0)" + exit 1 +fi + +echo "βœ… Extracted version from $PUBSPEC_PATH: $VERSION" +echo "$VERSION" diff --git a/.github/scripts/generate-tag-name.sh b/.github/scripts/generate-tag-name.sh new file mode 100755 index 00000000..a02629fe --- /dev/null +++ b/.github/scripts/generate-tag-name.sh @@ -0,0 +1,18 @@ +#!/bin/bash +# Generate tag name for mobile release +# Usage: ./generate-tag-name.sh + +set -e + +APP=$1 +ENV=$2 +VERSION=$3 + +if [ -z "$APP" ] || [ -z "$ENV" ] || [ -z "$VERSION" ]; then + echo "❌ Error: Missing required parameters" + echo "Usage: ./generate-tag-name.sh " + exit 1 +fi + +TAG_NAME="krow-withus-${APP}-mobile/${ENV}-v${VERSION}" +echo "$TAG_NAME" diff --git a/.github/workflows/mobile-release.yml b/.github/workflows/mobile-release.yml index 00dba7d3..4caadd0a 100644 --- a/.github/workflows/mobile-release.yml +++ b/.github/workflows/mobile-release.yml @@ -1,34 +1,30 @@ -name: Mobile Release +name: πŸ“± Mobile Release on: workflow_dispatch: inputs: app: - description: 'Mobile App' + description: 'πŸ“± Mobile App' required: true type: choice options: - worker - client environment: - description: 'Environment' + description: '🌍 Environment' required: true type: choice options: - dev - stage - prod - version: - description: 'Version (e.g., 0.1.0)' - required: true - type: string create_github_release: - description: 'Create GitHub Release' + description: 'πŸ“¦ Create GitHub Release' required: true type: boolean default: true prerelease: - description: 'Mark as Pre-release' + description: 'πŸ”– Mark as Pre-release' required: false type: boolean default: false @@ -46,96 +42,47 @@ jobs: with: fetch-depth: 0 - - name: πŸ” Validate version format + - name: οΏ½ Make scripts executable run: | - VERSION="${{ github.event.inputs.version }}" - if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then - echo "❌ Error: Version must be in format X.Y.Z (e.g., 0.1.0)" - exit 1 - fi - echo "βœ… Version format valid: $VERSION" + chmod +x .github/scripts/*.sh + echo "βœ… Scripts are now executable" + + - name: πŸ“– Extract version from pubspec.yaml + id: version + run: | + VERSION=$(.github/scripts/extract-version.sh "${{ github.event.inputs.app }}") + echo "version=${VERSION}" >> $GITHUB_OUTPUT + echo "πŸ“Œ Extracted version: ${VERSION}" - name: 🏷️ Generate tag name id: tag run: | - APP="${{ github.event.inputs.app }}" - ENV="${{ github.event.inputs.environment }}" - VERSION="${{ github.event.inputs.version }}" - - TAG_NAME="krow-withus-${APP}-mobile/${ENV}-v${VERSION}" + TAG_NAME=$(.github/scripts/generate-tag-name.sh \ + "${{ github.event.inputs.app }}" \ + "${{ github.event.inputs.environment }}" \ + "${{ steps.version.outputs.version }}") echo "tag_name=${TAG_NAME}" >> $GITHUB_OUTPUT - echo "πŸ“Œ Tag to create: ${TAG_NAME}" + echo "🎯 Tag to create: ${TAG_NAME}" - name: πŸ” Check if tag already exists run: | TAG_NAME="${{ steps.tag.outputs.tag_name }}" if git rev-parse "$TAG_NAME" >/dev/null 2>&1; then echo "❌ Error: Tag $TAG_NAME already exists" + echo "πŸ’‘ Tip: Update the version in pubspec.yaml before creating a new release" exit 1 fi echo "βœ… Tag does not exist, proceeding..." - - name: πŸ“ Verify CHANGELOG exists - run: | - APP="${{ github.event.inputs.app }}" - if [ "$APP" = "worker" ]; then - CHANGELOG_PATH="apps/mobile/apps/staff/CHANGELOG.md" - else - CHANGELOG_PATH="apps/mobile/apps/client/CHANGELOG.md" - fi - - if [ ! -f "$CHANGELOG_PATH" ]; then - echo "⚠️ Warning: CHANGELOG not found at $CHANGELOG_PATH" - else - echo "βœ… CHANGELOG found at $CHANGELOG_PATH" - echo "changelog_path=${CHANGELOG_PATH}" >> $GITHUB_ENV - fi - - name: πŸ“‹ Extract release notes from CHANGELOG id: release_notes run: | - APP="${{ github.event.inputs.app }}" - VERSION="${{ github.event.inputs.version }}" - - if [ "$APP" = "worker" ]; then - CHANGELOG_PATH="apps/mobile/apps/staff/CHANGELOG.md" - APP_NAME="Staff Mobile App (Worker)" - else - CHANGELOG_PATH="apps/mobile/apps/client/CHANGELOG.md" - APP_NAME="Client Mobile App" - fi - - # Try to extract release notes for this version - if [ -f "$CHANGELOG_PATH" ]; then - # Extract section for this version - NOTES=$(awk "/## \[${VERSION}\]/,/^## \[/" "$CHANGELOG_PATH" | sed '1d;$d' | sed '/^$/d') - - if [ -z "$NOTES" ]; then - NOTES="Release $VERSION for $APP_NAME - -No CHANGELOG entry found for this version. Please update the CHANGELOG manually. - -**Environment:** ${{ github.event.inputs.environment }} -**Tag:** ${{ steps.tag.outputs.tag_name }}" - else - NOTES="# $APP_NAME - Release $VERSION - -$NOTES - ---- - -**Environment:** ${{ github.event.inputs.environment }} -**Tag:** ${{ steps.tag.outputs.tag_name }}" - fi - else - NOTES="Release $VERSION for $APP_NAME - -**Environment:** ${{ github.event.inputs.environment }} -**Tag:** ${{ steps.tag.outputs.tag_name }}" - fi - - # Save to file to handle multiline - echo "$NOTES" > /tmp/release_notes.md + .github/scripts/extract-release-notes.sh \ + "${{ github.event.inputs.app }}" \ + "${{ steps.version.outputs.version }}" \ + "${{ github.event.inputs.environment }}" \ + "${{ steps.tag.outputs.tag_name }}" \ + "/tmp/release_notes.md" echo "notes_file=/tmp/release_notes.md" >> $GITHUB_OUTPUT - name: 🏷️ Create Git Tag @@ -143,12 +90,12 @@ $NOTES TAG_NAME="${{ steps.tag.outputs.tag_name }}" APP="${{ github.event.inputs.app }}" ENV="${{ github.event.inputs.environment }}" - VERSION="${{ github.event.inputs.version }}" + VERSION="${{ steps.version.outputs.version }}" git config user.name "github-actions[bot]" git config user.email "github-actions[bot]@users.noreply.github.com" - git tag -a "$TAG_NAME" -m "Release ${APP} mobile app ${VERSION} to ${ENV}" + git tag -a "$TAG_NAME" -m "πŸš€ Release ${APP} mobile app ${VERSION} to ${ENV}" git push origin "$TAG_NAME" echo "βœ… Tag created and pushed: $TAG_NAME" @@ -161,7 +108,7 @@ $NOTES TAG_NAME="${{ steps.tag.outputs.tag_name }}" APP="${{ github.event.inputs.app }}" ENV="${{ github.event.inputs.environment }}" - VERSION="${{ github.event.inputs.version }}" + VERSION="${{ steps.version.outputs.version }}" # Generate release title if [ "$APP" = "worker" ]; then @@ -173,43 +120,26 @@ $NOTES ENV_UPPER=$(echo "$ENV" | tr '[:lower:]' '[:upper:]') RELEASE_NAME="Krow With Us - ${APP_DISPLAY} - ${ENV_UPPER} - v${VERSION}" + echo "πŸ“¦ Creating GitHub Release: $RELEASE_NAME" + # Create release if [ "${{ github.event.inputs.prerelease }}" = "true" ]; then gh release create "$TAG_NAME" \ --title "$RELEASE_NAME" \ --notes-file "${{ steps.release_notes.outputs.notes_file }}" \ --prerelease + echo "πŸ”– Pre-release created successfully" else gh release create "$TAG_NAME" \ --title "$RELEASE_NAME" \ --notes-file "${{ steps.release_notes.outputs.notes_file }}" + echo "βœ… Release created successfully" fi - echo "βœ… GitHub Release created: $RELEASE_NAME" - - - name: πŸ“Š Release Summary + - name: πŸ“Š Generate Release Summary run: | - echo "## πŸš€ Release Created Successfully" >> $GITHUB_STEP_SUMMARY - echo "" >> $GITHUB_STEP_SUMMARY - echo "**App:** ${{ github.event.inputs.app }}" >> $GITHUB_STEP_SUMMARY - echo "**Environment:** ${{ github.event.inputs.environment }}" >> $GITHUB_STEP_SUMMARY - echo "**Version:** ${{ github.event.inputs.version }}" >> $GITHUB_STEP_SUMMARY - echo "**Tag:** \`${{ steps.tag.outputs.tag_name }}\`" >> $GITHUB_STEP_SUMMARY - echo "" >> $GITHUB_STEP_SUMMARY - - if [ "${{ github.event.inputs.app }}" = "worker" ]; then - APP_DISPLAY="Worker Mobile" - else - APP_DISPLAY="Client Mobile" - fi - ENV_UPPER=$(echo "${{ github.event.inputs.environment }}" | tr '[:lower:]' '[:upper:]') - RELEASE_NAME="Krow With Us - ${APP_DISPLAY} - ${ENV_UPPER} - v${{ github.event.inputs.version }}" - - echo "**Release Name:** $RELEASE_NAME" >> $GITHUB_STEP_SUMMARY - echo "" >> $GITHUB_STEP_SUMMARY - echo "### Next Steps" >> $GITHUB_STEP_SUMMARY - echo "" >> $GITHUB_STEP_SUMMARY - echo "1. Verify the tag and release on GitHub" >> $GITHUB_STEP_SUMMARY - echo "2. Trigger CodeMagic build (if configured)" >> $GITHUB_STEP_SUMMARY - echo "3. Monitor app store deployment" >> $GITHUB_STEP_SUMMARY - echo "4. Update project documentation if needed" >> $GITHUB_STEP_SUMMARY + .github/scripts/create-release-summary.sh \ + "${{ github.event.inputs.app }}" \ + "${{ github.event.inputs.environment }}" \ + "${{ steps.version.outputs.version }}" \ + "${{ steps.tag.outputs.tag_name }}" From 3e31002d1e868c41abce1eb34897ac201f659796 Mon Sep 17 00:00:00 2001 From: Achintha Isuru Date: Thu, 5 Mar 2026 11:58:28 -0500 Subject: [PATCH 11/15] refactor(ci): replace mobile-specific terms with generic product terminology MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit πŸ”„ Updated workflows and scripts to use product-agnostic naming: Workflow Changes: - πŸ“± Mobile Release β†’ πŸ“¦ Product Release - 🚨 Mobile Hotfix β†’ 🚨 Product Hotfix - Mobile App β†’ Product (in descriptions) - "mobile app" β†’ "product" (in messages and tags) - "pubspec.yaml" β†’ "version file" (in user-facing text) Display Names: - Worker Mobile β†’ Worker Product - Client Mobile β†’ Client Product - Staff Mobile App β†’ Staff Product (Worker) - Client Mobile App β†’ Client Product Benefits: βœ… Makes workflows extensible for other product types βœ… Consistent terminology across all automation βœ… Easier to add web, backend, or other products later βœ… Keeps implementation details (paths, scripts) unchanged βœ… Maintains backward compatibility with existing tags Note: File paths remain unchanged (apps/mobile/...) as they are implementation-specific --- .github/scripts/create-release-summary.sh | 4 ++-- .github/scripts/extract-release-notes.sh | 4 ++-- .github/scripts/extract-version.sh | 6 +++--- .github/scripts/generate-tag-name.sh | 2 +- .github/workflows/mobile-hotfix.yml | 20 ++++++++++---------- .github/workflows/mobile-release.yml | 16 ++++++++-------- 6 files changed, 26 insertions(+), 26 deletions(-) diff --git a/.github/scripts/create-release-summary.sh b/.github/scripts/create-release-summary.sh index 9b182968..54499bfc 100755 --- a/.github/scripts/create-release-summary.sh +++ b/.github/scripts/create-release-summary.sh @@ -17,10 +17,10 @@ fi # Determine display names if [ "$APP" = "worker" ]; then - APP_DISPLAY="Worker Mobile" + APP_DISPLAY="Worker Product" APP_EMOJI="πŸ‘·" else - APP_DISPLAY="Client Mobile" + APP_DISPLAY="Client Product" APP_EMOJI="πŸ’Ό" fi diff --git a/.github/scripts/extract-release-notes.sh b/.github/scripts/extract-release-notes.sh index 31c59f2b..292bbd65 100755 --- a/.github/scripts/extract-release-notes.sh +++ b/.github/scripts/extract-release-notes.sh @@ -19,10 +19,10 @@ fi # Determine CHANGELOG path and app name if [ "$APP" = "worker" ]; then CHANGELOG_PATH="apps/mobile/apps/staff/CHANGELOG.md" - APP_NAME="Staff Mobile App (Worker)" + APP_NAME="Staff Product (Worker)" else CHANGELOG_PATH="apps/mobile/apps/client/CHANGELOG.md" - APP_NAME="Client Mobile App" + APP_NAME="Client Product" fi # Try to extract release notes for this version diff --git a/.github/scripts/extract-version.sh b/.github/scripts/extract-version.sh index 0df25d72..dc1eed76 100755 --- a/.github/scripts/extract-version.sh +++ b/.github/scripts/extract-version.sh @@ -1,5 +1,5 @@ #!/bin/bash -# Extract version from pubspec.yaml for mobile apps +# Extract version from version file for products # Usage: ./extract-version.sh # app: worker or client @@ -15,10 +15,10 @@ fi # Determine pubspec path if [ "$APP" = "worker" ]; then PUBSPEC_PATH="apps/mobile/apps/staff/pubspec.yaml" - APP_NAME="Staff Mobile App (Worker)" + APP_NAME="Staff Product (Worker)" else PUBSPEC_PATH="apps/mobile/apps/client/pubspec.yaml" - APP_NAME="Client Mobile App" + APP_NAME="Client Product" fi # Check if pubspec exists diff --git a/.github/scripts/generate-tag-name.sh b/.github/scripts/generate-tag-name.sh index a02629fe..3784c5af 100755 --- a/.github/scripts/generate-tag-name.sh +++ b/.github/scripts/generate-tag-name.sh @@ -1,5 +1,5 @@ #!/bin/bash -# Generate tag name for mobile release +# Generate tag name for product release # Usage: ./generate-tag-name.sh set -e diff --git a/.github/workflows/mobile-hotfix.yml b/.github/workflows/mobile-hotfix.yml index cd2df197..a8261ef7 100644 --- a/.github/workflows/mobile-hotfix.yml +++ b/.github/workflows/mobile-hotfix.yml @@ -1,21 +1,21 @@ -name: Mobile Hotfix +name: 🚨 Product Hotfix on: workflow_dispatch: inputs: app: - description: 'Mobile App' + description: 'πŸ“¦ Product' required: true type: choice options: - worker - client production_tag: - description: 'Current Production Tag (e.g., krow-withus-worker-mobile/prod-v0.1.0)' + description: '🏷️ Current Production Tag (e.g., krow-withus-worker-mobile/prod-v0.1.0)' required: true type: string issue_description: - description: 'Brief issue description' + description: 'πŸ“ Brief issue description' required: true type: string @@ -118,11 +118,11 @@ jobs: if [ "$APP" = "worker" ]; then PUBSPEC_PATH="apps/mobile/apps/staff/pubspec.yaml" CHANGELOG_PATH="apps/mobile/apps/staff/CHANGELOG.md" - APP_NAME="Staff Mobile App" + APP_NAME="Staff Product" else PUBSPEC_PATH="apps/mobile/apps/client/pubspec.yaml" CHANGELOG_PATH="apps/mobile/apps/client/CHANGELOG.md" - APP_NAME="Client Mobile App" + APP_NAME="Client Product" fi # Update pubspec.yaml version @@ -150,10 +150,10 @@ jobs: if [ "$APP" = "worker" ]; then CHANGELOG_PATH="apps/mobile/apps/staff/CHANGELOG.md" - APP_NAME="Staff Mobile App" + APP_NAME="Staff Product" else CHANGELOG_PATH="apps/mobile/apps/client/CHANGELOG.md" - APP_NAME="Client Mobile App" + APP_NAME="Client Product" fi if [ -f "$CHANGELOG_PATH" ]; then @@ -216,9 +216,9 @@ From production tag: ${{ github.event.inputs.production_tag }}" APP="${{ github.event.inputs.app }}" if [ "$APP" = "worker" ]; then - APP_DISPLAY="Worker Mobile" + APP_DISPLAY="Worker Product" else - APP_DISPLAY="Client Mobile" + APP_DISPLAY="Client Product" fi PR_TITLE="🚨 HOTFIX: ${APP_DISPLAY} v${HOTFIX_VERSION} - ${ISSUE}" diff --git a/.github/workflows/mobile-release.yml b/.github/workflows/mobile-release.yml index 4caadd0a..6ff12819 100644 --- a/.github/workflows/mobile-release.yml +++ b/.github/workflows/mobile-release.yml @@ -1,10 +1,10 @@ -name: πŸ“± Mobile Release +name: οΏ½ Product Release on: workflow_dispatch: inputs: app: - description: 'πŸ“± Mobile App' + description: 'πŸ“¦ Product' required: true type: choice options: @@ -31,7 +31,7 @@ on: jobs: validate-and-create-release: - name: πŸš€ Create Mobile Release + name: πŸš€ Create Product Release runs-on: ubuntu-latest permissions: contents: write @@ -47,7 +47,7 @@ jobs: chmod +x .github/scripts/*.sh echo "βœ… Scripts are now executable" - - name: πŸ“– Extract version from pubspec.yaml + - name: πŸ“– Extract version from version file id: version run: | VERSION=$(.github/scripts/extract-version.sh "${{ github.event.inputs.app }}") @@ -69,7 +69,7 @@ jobs: TAG_NAME="${{ steps.tag.outputs.tag_name }}" if git rev-parse "$TAG_NAME" >/dev/null 2>&1; then echo "❌ Error: Tag $TAG_NAME already exists" - echo "πŸ’‘ Tip: Update the version in pubspec.yaml before creating a new release" + echo "πŸ’‘ Tip: Update the version in the version file before creating a new release" exit 1 fi echo "βœ… Tag does not exist, proceeding..." @@ -95,7 +95,7 @@ jobs: git config user.name "github-actions[bot]" git config user.email "github-actions[bot]@users.noreply.github.com" - git tag -a "$TAG_NAME" -m "πŸš€ Release ${APP} mobile app ${VERSION} to ${ENV}" + git tag -a "$TAG_NAME" -m "πŸš€ Release ${APP} product ${VERSION} to ${ENV}" git push origin "$TAG_NAME" echo "βœ… Tag created and pushed: $TAG_NAME" @@ -112,9 +112,9 @@ jobs: # Generate release title if [ "$APP" = "worker" ]; then - APP_DISPLAY="Worker Mobile" + APP_DISPLAY="Worker Product" else - APP_DISPLAY="Client Mobile" + APP_DISPLAY="Client Product" fi ENV_UPPER=$(echo "$ENV" | tr '[:lower:]' '[:upper:]') From 4ec1b2ca265882056dbd1f60d6d49c2365abe520 Mon Sep 17 00:00:00 2001 From: Achintha Isuru Date: Thu, 5 Mar 2026 12:07:32 -0500 Subject: [PATCH 12/15] refactor(ci): enhance hotfix workflow and rename workflow files MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit πŸ”„ Hotfix Workflow Enhancements: - Accept tags from any environment (dev/stage/prod), not just production - Changed input parameter: 'production_tag' β†’ 'tag' - Updated validation to show all available tags (not just prod) - Made terminology more generic throughout - Show 20 most recent tags instead of 10 for better visibility πŸ“ File Renames: - .github/workflows/mobile-hotfix.yml β†’ hotfix-branch-creation.yml - .github/workflows/mobile-release.yml β†’ product-release.yml Benefits: βœ… Hotfix workflow now works with dev/stage/prod tags βœ… More flexible for various hotfix scenarios βœ… Clearer, more descriptive workflow file names βœ… Consistent with product-agnostic terminology --- ...-hotfix.yml => hotfix-branch-creation.yml} | 30 +++++++++---------- ...mobile-release.yml => product-release.yml} | 4 +-- 2 files changed, 17 insertions(+), 17 deletions(-) rename .github/workflows/{mobile-hotfix.yml => hotfix-branch-creation.yml} (92%) rename .github/workflows/{mobile-release.yml => product-release.yml} (97%) diff --git a/.github/workflows/mobile-hotfix.yml b/.github/workflows/hotfix-branch-creation.yml similarity index 92% rename from .github/workflows/mobile-hotfix.yml rename to .github/workflows/hotfix-branch-creation.yml index a8261ef7..2732b458 100644 --- a/.github/workflows/mobile-hotfix.yml +++ b/.github/workflows/hotfix-branch-creation.yml @@ -10,8 +10,8 @@ on: options: - worker - client - production_tag: - description: '🏷️ Current Production Tag (e.g., krow-withus-worker-mobile/prod-v0.1.0)' + tag: + description: '🏷️ Current Tag (e.g., krow-withus-worker-mobile/prod-v0.1.0 or dev/stage)' required: true type: string issue_description: @@ -33,19 +33,19 @@ jobs: with: fetch-depth: 0 - - name: πŸ” Validate production tag exists + - name: πŸ” Validate tag exists id: validate_tag run: | - TAG="${{ github.event.inputs.production_tag }}" + TAG="${{ github.event.inputs.tag }}" if ! git rev-parse "$TAG" >/dev/null 2>&1; then - echo "❌ Error: Production tag '$TAG' does not exist" + echo "❌ Error: Tag '$TAG' does not exist" echo "Available tags:" - git tag -l "krow-withus-*-mobile/prod-*" | tail -10 + git tag -l "krow-withus-*-mobile/*" | tail -20 exit 1 fi - echo "βœ… Production tag exists: $TAG" + echo "βœ… Tag exists: $TAG" # Extract version from tag VERSION=$(echo "$TAG" | grep -oP 'v\K[0-9]+\.[0-9]+\.[0-9]+' || echo "") @@ -55,7 +55,7 @@ jobs: fi echo "current_version=${VERSION}" >> $GITHUB_OUTPUT - echo "πŸ“Œ Current production version: $VERSION" + echo "πŸ“Œ Current version: $VERSION" - name: πŸ”’ Calculate hotfix version id: hotfix_version @@ -93,15 +93,15 @@ jobs: echo "βœ… Branch does not exist, proceeding..." - - name: 🌿 Create hotfix branch from production tag + - name: 🌿 Create hotfix branch from tag run: | - TAG="${{ github.event.inputs.production_tag }}" + TAG="${{ github.event.inputs.tag }}" BRANCH="${{ steps.branch.outputs.branch_name }}" git config user.name "github-actions[bot]" git config user.email "github-actions[bot]@users.noreply.github.com" - # Checkout the production tag + # Checkout the tag git checkout "$TAG" # Create new branch @@ -193,7 +193,7 @@ HOTFIX: ${ISSUE} - Add CHANGELOG entry - Ready for bug fix commits -From production tag: ${{ github.event.inputs.production_tag }}" +From tag: ${{ github.event.inputs.tag }}" echo "βœ… Committed version changes" @@ -223,11 +223,11 @@ From production tag: ${{ github.event.inputs.production_tag }}" PR_TITLE="🚨 HOTFIX: ${APP_DISPLAY} v${HOTFIX_VERSION} - ${ISSUE}" - PR_BODY="## 🚨 HOTFIX - URGENT PRODUCTION FIX + PR_BODY="## 🚨 HOTFIX - URGENT FIX **App:** ${APP_DISPLAY} **Version:** ${HOTFIX_VERSION} -**From:** \`${{ github.event.inputs.production_tag }}\` +**From:** \`${{ github.event.inputs.tag }}\` ### Issue ${ISSUE} @@ -289,7 +289,7 @@ git push origin krow-withus-${APP}-mobile/prod-v${HOTFIX_VERSION} echo "" >> $GITHUB_STEP_SUMMARY echo "**App:** ${{ github.event.inputs.app }}" >> $GITHUB_STEP_SUMMARY echo "**Issue:** ${{ github.event.inputs.issue_description }}" >> $GITHUB_STEP_SUMMARY - echo "**From Tag:** \`${{ github.event.inputs.production_tag }}\`" >> $GITHUB_STEP_SUMMARY + echo "**From Tag:** \`${{ github.event.inputs.tag }}\`" >> $GITHUB_STEP_SUMMARY echo "**Current Version:** ${{ steps.validate_tag.outputs.current_version }}" >> $GITHUB_STEP_SUMMARY echo "**Hotfix Version:** ${{ steps.hotfix_version.outputs.hotfix_version }}" >> $GITHUB_STEP_SUMMARY echo "**Branch:** \`${{ steps.branch.outputs.branch_name }}\`" >> $GITHUB_STEP_SUMMARY diff --git a/.github/workflows/mobile-release.yml b/.github/workflows/product-release.yml similarity index 97% rename from .github/workflows/mobile-release.yml rename to .github/workflows/product-release.yml index 6ff12819..c66a80ca 100644 --- a/.github/workflows/mobile-release.yml +++ b/.github/workflows/product-release.yml @@ -112,9 +112,9 @@ jobs: # Generate release title if [ "$APP" = "worker" ]; then - APP_DISPLAY="Worker Product" + APP_DISPLAY="Worker Mobile Application" else - APP_DISPLAY="Client Product" + APP_DISPLAY="Client Mobile Application" fi ENV_UPPER=$(echo "$ENV" | tr '[:lower:]' '[:upper:]') From 39f0d9d53ce44f9321cc2f8f940a5d2dea589c26 Mon Sep 17 00:00:00 2001 From: Achintha Isuru Date: Thu, 5 Mar 2026 12:11:45 -0500 Subject: [PATCH 13/15] refactor(ci): update product options to be more specific MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit πŸ”„ Changed product option values: - worker β†’ worker-mobile-app - client β†’ client-mobile-app πŸ“ Updated Files: - .github/workflows/hotfix-branch-creation.yml - .github/workflows/product-release.yml - .github/scripts/extract-version.sh - .github/scripts/extract-release-notes.sh - .github/scripts/create-release-summary.sh - .github/scripts/generate-tag-name.sh 🎯 Key Changes: - Product dropdown options now more specific - All conditional checks updated to use new values - Tag/branch names remain clean (strips -mobile-app suffix) - Tag format unchanged: krow-withus-worker-mobile/prod-v0.1.0 - Branch format unchanged: hotfix/krow-withus-worker-mobile-v0.1.0 Benefits: βœ… Clearer product selection (distinguishes mobile from future web/backend) βœ… Backward compatible tag format βœ… Maintains clean naming conventions --- .github/scripts/create-release-summary.sh | 2 +- .github/scripts/extract-release-notes.sh | 2 +- .github/scripts/extract-version.sh | 6 ++-- .github/scripts/generate-tag-name.sh | 6 +++- .github/workflows/hotfix-branch-creation.yml | 29 +++++++++++++------- .github/workflows/product-release.yml | 6 ++-- 6 files changed, 32 insertions(+), 19 deletions(-) diff --git a/.github/scripts/create-release-summary.sh b/.github/scripts/create-release-summary.sh index 54499bfc..ddefb1d9 100755 --- a/.github/scripts/create-release-summary.sh +++ b/.github/scripts/create-release-summary.sh @@ -16,7 +16,7 @@ if [ -z "$APP" ] || [ -z "$ENV" ] || [ -z "$VERSION" ] || [ -z "$TAG_NAME" ]; th fi # Determine display names -if [ "$APP" = "worker" ]; then +if [ "$APP" = "worker-mobile-app" ]; then APP_DISPLAY="Worker Product" APP_EMOJI="πŸ‘·" else diff --git a/.github/scripts/extract-release-notes.sh b/.github/scripts/extract-release-notes.sh index 292bbd65..f29530fe 100755 --- a/.github/scripts/extract-release-notes.sh +++ b/.github/scripts/extract-release-notes.sh @@ -17,7 +17,7 @@ if [ -z "$APP" ] || [ -z "$VERSION" ] || [ -z "$ENV" ] || [ -z "$TAG_NAME" ] || fi # Determine CHANGELOG path and app name -if [ "$APP" = "worker" ]; then +if [ "$APP" = "worker-mobile-app" ]; then CHANGELOG_PATH="apps/mobile/apps/staff/CHANGELOG.md" APP_NAME="Staff Product (Worker)" else diff --git a/.github/scripts/extract-version.sh b/.github/scripts/extract-version.sh index dc1eed76..88d97dd8 100755 --- a/.github/scripts/extract-version.sh +++ b/.github/scripts/extract-version.sh @@ -1,19 +1,19 @@ #!/bin/bash # Extract version from version file for products # Usage: ./extract-version.sh -# app: worker or client +# app: worker-mobile-app or client-mobile-app set -e APP=$1 if [ -z "$APP" ]; then - echo "❌ Error: App parameter required (worker or client)" + echo "❌ Error: App parameter required (worker-mobile-app or client-mobile-app)" exit 1 fi # Determine pubspec path -if [ "$APP" = "worker" ]; then +if [ "$APP" = "worker-mobile-app" ]; then PUBSPEC_PATH="apps/mobile/apps/staff/pubspec.yaml" APP_NAME="Staff Product (Worker)" else diff --git a/.github/scripts/generate-tag-name.sh b/.github/scripts/generate-tag-name.sh index 3784c5af..c779b542 100755 --- a/.github/scripts/generate-tag-name.sh +++ b/.github/scripts/generate-tag-name.sh @@ -14,5 +14,9 @@ if [ -z "$APP" ] || [ -z "$ENV" ] || [ -z "$VERSION" ]; then exit 1 fi -TAG_NAME="krow-withus-${APP}-mobile/${ENV}-v${VERSION}" +# Strip -mobile-app suffix from app name for cleaner tag names +# worker-mobile-app -> worker, client-mobile-app -> client +APP_TAG=$(echo "$APP" | sed 's/-mobile-app$//') + +TAG_NAME="krow-withus-${APP_TAG}-mobile/${ENV}-v${VERSION}" echo "$TAG_NAME" diff --git a/.github/workflows/hotfix-branch-creation.yml b/.github/workflows/hotfix-branch-creation.yml index 2732b458..4a1a9e45 100644 --- a/.github/workflows/hotfix-branch-creation.yml +++ b/.github/workflows/hotfix-branch-creation.yml @@ -8,8 +8,8 @@ on: required: true type: choice options: - - worker - - client + - worker-mobile-app + - client-mobile-app tag: description: '🏷️ Current Tag (e.g., krow-withus-worker-mobile/prod-v0.1.0 or dev/stage)' required: true @@ -78,7 +78,10 @@ jobs: APP="${{ github.event.inputs.app }}" VERSION="${{ steps.hotfix_version.outputs.hotfix_version }}" - BRANCH_NAME="hotfix/krow-withus-${APP}-mobile-v${VERSION}" + # Strip -mobile-app suffix for cleaner branch names + APP_CLEAN=$(echo "$APP" | sed 's/-mobile-app$//') + + BRANCH_NAME="hotfix/krow-withus-${APP_CLEAN}-mobile-v${VERSION}" echo "branch_name=${BRANCH_NAME}" >> $GITHUB_OUTPUT echo "🌿 Branch to create: $BRANCH_NAME" @@ -115,7 +118,7 @@ jobs: APP="${{ github.event.inputs.app }}" HOTFIX_VERSION="${{ steps.hotfix_version.outputs.hotfix_version }}" - if [ "$APP" = "worker" ]; then + if [ "$APP" = "worker-mobile-app" ]; then PUBSPEC_PATH="apps/mobile/apps/staff/pubspec.yaml" CHANGELOG_PATH="apps/mobile/apps/staff/CHANGELOG.md" APP_NAME="Staff Product" @@ -148,7 +151,7 @@ jobs: HOTFIX_VERSION="${{ steps.hotfix_version.outputs.hotfix_version }}" ISSUE="${{ github.event.inputs.issue_description }}" - if [ "$APP" = "worker" ]; then + if [ "$APP" = "worker-mobile-app" ]; then CHANGELOG_PATH="apps/mobile/apps/staff/CHANGELOG.md" APP_NAME="Staff Product" else @@ -215,7 +218,10 @@ From tag: ${{ github.event.inputs.tag }}" ISSUE="${{ github.event.inputs.issue_description }}" APP="${{ github.event.inputs.app }}" - if [ "$APP" = "worker" ]; then + # Strip -mobile-app suffix for cleaner tag names + APP_CLEAN=$(echo "$APP" | sed 's/-mobile-app$//') + + if [ "$APP" = "worker-mobile-app" ]; then APP_DISPLAY="Worker Product" else APP_DISPLAY="Client Product" @@ -264,8 +270,8 @@ git push origin $BRANCH # Tag and release git checkout main git pull origin main -git tag -a krow-withus-${APP}-mobile/prod-v${HOTFIX_VERSION} -m \"HOTFIX: ${ISSUE}\" -git push origin krow-withus-${APP}-mobile/prod-v${HOTFIX_VERSION} +git tag -a krow-withus-${APP_CLEAN}-mobile/prod-v${HOTFIX_VERSION} -m \"HOTFIX: ${ISSUE}\" +git push origin krow-withus-${APP_CLEAN}-mobile/prod-v${HOTFIX_VERSION} \`\`\` --- @@ -285,6 +291,9 @@ git push origin krow-withus-${APP}-mobile/prod-v${HOTFIX_VERSION} - name: πŸ“Š Hotfix Summary run: | + # Strip -mobile-app suffix for cleaner tag names + APP_CLEAN=$(echo "${{ github.event.inputs.app }}" | sed 's/-mobile-app$//') + echo "## 🚨 Hotfix Branch Created" >> $GITHUB_STEP_SUMMARY echo "" >> $GITHUB_STEP_SUMMARY echo "**App:** ${{ github.event.inputs.app }}" >> $GITHUB_STEP_SUMMARY @@ -312,8 +321,8 @@ git push origin krow-withus-${APP}-mobile/prod-v${HOTFIX_VERSION} echo " \`\`\`bash" >> $GITHUB_STEP_SUMMARY echo " git checkout main" >> $GITHUB_STEP_SUMMARY echo " git pull origin main" >> $GITHUB_STEP_SUMMARY - echo " git tag -a krow-withus-${{ github.event.inputs.app }}-mobile/prod-v${{ steps.hotfix_version.outputs.hotfix_version }} -m \"HOTFIX: ${{ github.event.inputs.issue_description }}\"" >> $GITHUB_STEP_SUMMARY - echo " git push origin krow-withus-${{ github.event.inputs.app }}-mobile/prod-v${{ steps.hotfix_version.outputs.hotfix_version }}" >> $GITHUB_STEP_SUMMARY + echo " git tag -a krow-withus-${APP_CLEAN}-mobile/prod-v${{ steps.hotfix_version.outputs.hotfix_version }} -m \"HOTFIX: ${{ github.event.inputs.issue_description }}\"" >> $GITHUB_STEP_SUMMARY + echo " git push origin krow-withus-${APP_CLEAN}-mobile/prod-v${{ steps.hotfix_version.outputs.hotfix_version }}" >> $GITHUB_STEP_SUMMARY echo " \`\`\`" >> $GITHUB_STEP_SUMMARY echo "" >> $GITHUB_STEP_SUMMARY diff --git a/.github/workflows/product-release.yml b/.github/workflows/product-release.yml index c66a80ca..a72d35e5 100644 --- a/.github/workflows/product-release.yml +++ b/.github/workflows/product-release.yml @@ -8,8 +8,8 @@ on: required: true type: choice options: - - worker - - client + - worker-mobile-app + - client-mobile-app environment: description: '🌍 Environment' required: true @@ -111,7 +111,7 @@ jobs: VERSION="${{ steps.version.outputs.version }}" # Generate release title - if [ "$APP" = "worker" ]; then + if [ "$APP" = "worker-mobile-app" ]; then APP_DISPLAY="Worker Mobile Application" else APP_DISPLAY="Client Mobile Application" From 7e52b19dd5face1f4cdbbe9813ff3d7afe07f952 Mon Sep 17 00:00:00 2001 From: Achintha Isuru Date: Thu, 5 Mar 2026 12:16:54 -0500 Subject: [PATCH 14/15] docs: remove outdated root-level release documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit πŸ—‘οΈ Removed Files: - RELEASE_IMPLEMENTATION.md - RELEASE_INDEX.md - RELEASE_PACKAGE_SUMMARY.md - RELEASE_QUICK_REFERENCE.md - RELEASE_STRATEGY.md - RELEASE_VISUAL_GUIDE.md - RELEASE_WORKFLOW.md - VERSION_FILES_REFERENCE.md πŸ“ Reason for Removal: - These were draft/planning documents with incorrect tag format - Used 'staff-mobile/*' instead of correct 'krow-withus-worker-mobile/*' - Not aligned with actual GitHub Actions workflows - Caused confusion about which documentation to follow βœ… Current Documentation (Correct & Up-to-Date): - docs/RELEASE/MOBILE_RELEASE_PLAN.md - docs/RELEASE/HOTFIX_PROCESS.md - docs/RELEASE/OVERALL_RELEASE_PLAN.md The docs/RELEASE/ files use correct tag naming and align with the implemented GitHub Actions workflows (.github/workflows/product-release.yml and hotfix-branch-creation.yml). --- RELEASE_IMPLEMENTATION.md | 509 ------------------------------------- RELEASE_INDEX.md | 411 ------------------------------ RELEASE_PACKAGE_SUMMARY.md | 507 ------------------------------------ RELEASE_QUICK_REFERENCE.md | 267 ------------------- RELEASE_STRATEGY.md | 425 ------------------------------- RELEASE_VISUAL_GUIDE.md | 382 ---------------------------- RELEASE_WORKFLOW.md | 382 ---------------------------- VERSION_FILES_REFERENCE.md | 406 ----------------------------- 8 files changed, 3289 deletions(-) delete mode 100644 RELEASE_IMPLEMENTATION.md delete mode 100644 RELEASE_INDEX.md delete mode 100644 RELEASE_PACKAGE_SUMMARY.md delete mode 100644 RELEASE_QUICK_REFERENCE.md delete mode 100644 RELEASE_STRATEGY.md delete mode 100644 RELEASE_VISUAL_GUIDE.md delete mode 100644 RELEASE_WORKFLOW.md delete mode 100644 VERSION_FILES_REFERENCE.md 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 From c3c305c82754573f69d64155a2ee8416648d87d7 Mon Sep 17 00:00:00 2001 From: Achintha Isuru Date: Thu, 5 Mar 2026 12:25:25 -0500 Subject: [PATCH 15/15] feat: add pull request template for improved contribution guidelines --- .github/PULL_REQUEST_TEMPLATE.md | 101 +++++++++++++++++++++++++++++++ 1 file changed, 101 insertions(+) create mode 100644 .github/PULL_REQUEST_TEMPLATE.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..c7a2d1c5 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,101 @@ +## πŸ“‹ Description + + + + +--- + +## 🎯 Type of Change + + + +- [ ] πŸ› **Bug fix** (non-breaking change that fixes an issue) +- [ ] ✨ **Feature** (non-breaking change that adds functionality) +- [ ] πŸ“ **Documentation** (changes to docs, comments, or README) +- [ ] πŸ”§ **Refactor** (code change that doesn't affect functionality) +- [ ] ⚑ **Performance** (improvement in performance or optimization) +- [ ] πŸ” **Security** (security fix or improvement) +- [ ] 🎨 **Style** (formatting, linting, or minor code style changes) +- [ ] πŸ—οΈ **Architecture** (significant structural changes) + +--- + +## πŸ“¦ Affected Areas + + + +- [ ] πŸ“± **Mobile** (Flutter - Client/Worker app) +- [ ] 🌐 **Web** (React Dashboard) +- [ ] πŸ”Œ **Backend** (APIs, Data Connect, Cloud Functions) +- [ ] πŸ—„οΈ **Database** (Schema changes, migrations) +- [ ] πŸš€ **CI/CD** (GitHub Actions, deployment configs) +- [ ] πŸ“š **Documentation** (Docs, onboarding guides) + +--- + +## πŸ”— Related Issues + + + +Closes # +Related to # + +--- + +## βœ… Testing + + + +**Test Details:** + + + +--- + +## πŸ”„ Breaking Changes + + + +- [ ] No breaking changes +- [ ] Yes, breaking changes: + +**Details:** + + + +--- + +## 🎯 Checklist + + + +- [ ] Code follows project style guidelines +- [ ] Self-review completed +- [ ] Comments added for complex logic +- [ ] Documentation updated (if applicable) +- [ ] No new console warnings/errors +- [ ] Tests pass locally +- [ ] Branch is up-to-date with `dev` +- [ ] Commit messages are clear and descriptive +- [ ] Sensitive data is not committed +- [ ] Environment variables documented (if added) + +--- + +## πŸ“ Additional Notes + + + + +--- + +## πŸ” Review Checklist for Maintainers + +- [ ] Code quality and readability +- [ ] Design patterns follow project conventions +- [ ] Test coverage is adequate +- [ ] Performance implications reviewed +- [ ] Security concerns addressed +- [ ] Documentation is complete +- [ ] Breaking changes properly communicated +- [ ] Cross-platform compatibility (if applicable)