Krow/Krow-workspace
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: remove outdated root-level release documentation

Browse Source 
🗑️ 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).
This commit is contained in:
Achintha Isuru
2026-03-05 12:16:54 -05:00
parent 39f0d9d53c
commit 7e52b19dd5
8 changed files with 0 additions and 3289 deletions
Download Patch File Download Diff File Expand all files Collapse all files

509
RELEASE_IMPLEMENTATION.md
View File

@@ -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

411
RELEASE_INDEX.md
View File

@@ -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

507
RELEASE_PACKAGE_SUMMARY.md
View File

@@ -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: <product>/<environment>-v<version>
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

267
RELEASE_QUICK_REFERENCE.md
View File

@@ -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
```
<product>/<environment>-v<major>.<minor>.<patch>
Examples:
staff-mobile/dev-v0.2.0
client-mobile/staging-v0.2.0
web-dashboard/prod-v1.0.0
command-api/prod-v0.1.1
```
**Products:**
- `staff-mobile` / `client-mobile`
- `web-dashboard`
- `command-api` / `core-api`
- `dataconnect`
**Environments:**
- `dev` (development, unstable)
- `staging` (pre-production, testing)
- `prod` (production, stable)
---
## 📝 Checklist: Before You Tag
- [ ] Code review completed
- [ ] All tests passing locally
- [ ] CHANGELOG.md updated
- [ ] Version numbers updated in:
- [ ] `apps/mobile/apps/*/pubspec.yaml` (if mobile)
- [ ] `apps/web/package.json` (if web)
- [ ] `backend/*/package.json` (if backend)
- [ ] `codemagic.yaml` (if mobile)
- [ ] Committed and pushed changes
- [ ] Ready to merge release branch
---
## 🚀 Create a Release (Quick Steps)
```
1. Update version numbers
(See "Version File Locations" below)
2. Update CHANGELOG.md
Add line at top with date and version
3. Commit & push
git commit -m "chore: bump to v0.2.0"
git push origin release/branch-name
4. Create tag
git tag -a product/env-v0.2.0 -m "Description"
git push origin product/env-v0.2.0
5. Create GitHub Release
Go to Releases → Draft new release
Select tag → Fill in details → Publish
6. Deploy
(Follow your deployment script)
7. Monitor
Check logs for 24 hours
```
---
## 📍 Version File Locations
**Quick edit list for version bumps:**
### Mobile (Staff & Client)
- [ ] `apps/mobile/apps/staff_app/pubspec.yaml`
- [ ] `apps/mobile/apps/client_app/pubspec.yaml`
Format: `version: X.Y.Z+N` (N = build number)
### Web
- [ ] `apps/web/package.json`
Format: `"version": "X.Y.Z"`
### Backend
- [ ] `backend/command-api/package.json`
- [ ] `backend/core-api/package.json`
Format: `"version": "X.Y.Z"`
### CI/CD
- [ ] `codemagic.yaml`
Format: `build_version: "X.Y.Z"`
**Also update CHANGELOG.md!**
---
## 🔄 Release Timeline At-a-Glance
| Stage | Duration | Environment | Status | Next Step |
|-------|----------|-------------|--------|-----------|
| **Feature Dev** | 1-2 weeks | Local | 👨‍💻 In progress | Code review |
| **Code Review** | 1-3 days | GitHub | 👀 Reviewing | Merge to main |
| **Dev Release** | Same day | Dev env | ✅ Deployed | Weekly |
| **Staging Release** | 1 week | Staging | 🧪 Testing | QA sign-off |
| **Prod Release** | 2-3 hours | Production | 🚀 Deploying | 24h monitoring |
---
## 📞 Common Tasks
### I want to release Staff Mobile v0.2.0
```bash
git checkout -b release/staff-mobile-v0.2.0
# Edit: apps/mobile/apps/staff_app/pubspec.yaml (0.1.0 → 0.2.0)
# Edit: CHANGELOG.md (add entry)
git add .
git commit -m "chore: staff mobile v0.2.0"
git push origin release/staff-mobile-v0.2.0
# Create PR, get approved, merge
git tag -a staff-mobile/dev-v0.2.0 -m "Staff Mobile v0.2.0"
git push origin staff-mobile/dev-v0.2.0
```
### I found a critical bug in production
```bash
git checkout -b hotfix/staff-mobile-v0.1.1 staff-mobile/prod-v0.1.0
# Fix the bug
# Bump version 0.1.0 → 0.1.1 in pubspec.yaml
git commit -m "fix: [critical issue]"
git tag -a staff-mobile/prod-v0.1.1 -m "Hotfix: [issue]"
git push origin staff-mobile/prod-v0.1.1
# Deploy immediately, monitor 24h
```
### I want to see all production versions
```bash
git tag -l "*/prod-v*" --sort=-version:refname
```
### I want to compare two versions
```bash
git log staff-mobile/prod-v0.1.0...staff-mobile/prod-v0.2.0 --oneline
```
---
## 🎯 Deployment Order (Multi-Product Release)
Always deploy in this order:
1. **DataConnect** (if schema changed)
2. **Command API** + **Core API** (can be parallel)
3. **Web Dashboard**
4. **Staff Mobile** + **Client Mobile** (can be parallel)
Verify each step completes before moving to next.
---
## ⚠️ Red Flags 🚫
**DON'T tag if:**
- ❌ Tests are failing
- ❌ Code review not approved
- ❌ CHANGELOG not updated
- ❌ Version numbers not bumped
- ❌ Breaking changes not documented
- ❌ Staging not tested yet
- ❌ Team not notified
**DO tag if:**
- ✅ All tests passing
- ✅ Code reviewed + approved
- ✅ CHANGELOG updated
- ✅ Version numbers consistent
- ✅ Staged and tested
- ✅ Team aware
---
## 🆘 Troubleshoot
**Tag won't push:**
```bash
# Make sure you have push permissions
git config --list | grep remote.origin.url
# Re-authenticate if needed
git credential-osxkeychain erase host=github.com
```
**Wrong tag created:**
```bash
git tag -d wrong-tag
git push origin --delete wrong-tag
git tag -a correct-tag -m "message"
git push origin correct-tag
```
**Need to see what changed:**
```bash
git log v0.1.0..v0.2.0 --oneline
git diff v0.1.0..v0.2.0 -- apps/mobile/
```
---
## 📚 Full Documentation
For complete details, see:
- 📖 [RELEASE_STRATEGY.md](./RELEASE_STRATEGY.md) - Full strategy
- 🔧 [RELEASE_WORKFLOW.md](./RELEASE_WORKFLOW.md) - Step-by-step
- 🚀 [RELEASE_IMPLEMENTATION.md](./RELEASE_IMPLEMENTATION.md) - Setup guide
- 📊 [RELEASE_VISUAL_GUIDE.md](./RELEASE_VISUAL_GUIDE.md) - Diagrams
---
## 📞 Contact
**Release Questions?** Slack: #releases
**Need Help?** Check RELEASE_WORKFLOW.md or ask DevOps team
---
**Last Updated**: 2026-03-05
**Bookmark this page! 🔖**

425
RELEASE_STRATEGY.md
View File

@@ -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
```
<product>/<environment>-v<version>
```
### 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<version>`
- [ ] 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 <commit-hash> -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

382
RELEASE_VISUAL_GUIDE.md
View File

@@ -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

382
RELEASE_WORKFLOW.md
View File

@@ -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 <fixed-files>
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 <last-tag>..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 <env> <version>"
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

406
VERSION_FILES_REFERENCE.md
View File

@@ -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 <tag>`
---
## 🎯 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