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.
This commit is contained in:
Achintha Isuru
425
RELEASE_STRATEGY.md
Normal file
425
RELEASE_STRATEGY.md
Normal file
@@ -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
|
||||
|
||||
```
|
||||
<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
|
||||
Reference in New Issue
Block a user