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
509
RELEASE_IMPLEMENTATION.md
Normal file
509
RELEASE_IMPLEMENTATION.md
Normal file
@@ -0,0 +1,509 @@
|
||||
# Release Strategy Implementation Guide
|
||||
|
||||
This guide walks you through implementing the tagging and release strategy for KROW Workforce.
|
||||
|
||||
---
|
||||
|
||||
## 📍 Phase 1: Initial Setup (Do This First)
|
||||
|
||||
### Step 1: Review and Approve Strategy
|
||||
|
||||
1. Read [RELEASE_STRATEGY.md](./RELEASE_STRATEGY.md)
|
||||
2. Get team feedback
|
||||
3. Customize if needed (adjust cadence, naming, etc.)
|
||||
4. Commit to this approach
|
||||
|
||||
### Step 2: Verify Current State
|
||||
|
||||
Check current versions of all products:
|
||||
|
||||
```bash
|
||||
# Mobile
|
||||
cat apps/mobile/apps/staff_app/pubspec.yaml | grep "^version:"
|
||||
cat apps/mobile/apps/client_app/pubspec.yaml | grep "^version:"
|
||||
|
||||
# Web
|
||||
cat apps/web/package.json | grep '"version"'
|
||||
|
||||
# Backend
|
||||
cat backend/command-api/package.json | grep '"version"'
|
||||
cat backend/core-api/package.json | grep '"version"'
|
||||
```
|
||||
|
||||
Current expected state:
|
||||
```
|
||||
Staff Mobile: 0.1.0+?
|
||||
Client Mobile: 0.1.0+?
|
||||
Web Dashboard: 0.0.0
|
||||
Command API: 0.1.0
|
||||
Core API: 0.1.0
|
||||
```
|
||||
|
||||
### Step 3: Create Initial Dev Tags
|
||||
|
||||
Create retrospective tags for the current state. This establishes a baseline.
|
||||
|
||||
```bash
|
||||
# Navigate to repo
|
||||
cd /Users/achintha/Documents/GitHub/krow-workforce
|
||||
|
||||
# Create tags for current development versions
|
||||
# (These mark the current checkpoint, not retrospective releases)
|
||||
|
||||
git tag -a staff-mobile/dev-v0.1.0 -m "Staff Mobile v0.1.0 - Initial development release"
|
||||
git tag -a client-mobile/dev-v0.1.0 -m "Client Mobile v0.1.0 - Initial development release"
|
||||
git tag -a web-dashboard/dev-v0.0.0 -m "Web Dashboard v0.0.0 - Pre-release"
|
||||
git tag -a command-api/dev-v0.1.0 -m "Command API v0.1.0 - Initial development release"
|
||||
git tag -a core-api/dev-v0.1.0 -m "Core API v0.1.0 - Initial development release"
|
||||
|
||||
# Push all tags to remote
|
||||
git push origin --tags
|
||||
|
||||
# Verify tags were created
|
||||
git tag -l "*" --sort=-version:refname
|
||||
```
|
||||
|
||||
Expected output:
|
||||
```
|
||||
core-api/dev-v0.1.0
|
||||
command-api/dev-v0.1.0
|
||||
client-mobile/dev-v0.1.0
|
||||
staff-mobile/dev-v0.1.0
|
||||
web-dashboard/dev-v0.0.0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📍 Phase 2: GitHub Configuration
|
||||
|
||||
### Step 1: Enable Branch Protection for Production Tags
|
||||
|
||||
1. Go to your GitHub repo → Settings → Branches
|
||||
2. Click "Add rule"
|
||||
3. Configure as follows:
|
||||
|
||||
```
|
||||
Branch name pattern: */prod-v*
|
||||
|
||||
Require a pull request before merging: ✅ ON
|
||||
Require approvals: ✅ ON (1+ approvals)
|
||||
Dismiss stale pull request approvals: ✅ ON
|
||||
Require status checks to pass: ✅ ON
|
||||
Require branches to be up to date before merging: ✅ ON
|
||||
Include administrators: ✅ ON
|
||||
Allow force pushes: ❌ OFF
|
||||
Allow deletions: ❌ OFF
|
||||
```
|
||||
|
||||
4. Click "Create"
|
||||
|
||||
### Step 2: Configure Required Status Checks
|
||||
|
||||
Status checks that must pass before merging:
|
||||
- `build / test` - Unit and integration tests
|
||||
- `build / lint` - Code quality checks
|
||||
- `build / security-scan` - Security validation
|
||||
|
||||
(These should already exist from your CI/CD pipeline)
|
||||
|
||||
### Step 3: Setup Release Notes Template
|
||||
|
||||
1. Go to Settings → Releases → Set up a release
|
||||
2. Add this template:
|
||||
|
||||
```markdown
|
||||
## Release Notes: [Product] v[Version]
|
||||
|
||||
**Release Date**: [Date]
|
||||
**Environment**: [dev/staging/prod]
|
||||
|
||||
### 🎯 What's New
|
||||
|
||||
### ✨ Features
|
||||
- Feature 1
|
||||
- Feature 2
|
||||
|
||||
### 🔧 Improvements
|
||||
- Improvement 1
|
||||
- Improvement 2
|
||||
|
||||
### 🐛 Bug Fixes
|
||||
- Bug fix 1
|
||||
- Bug fix 2
|
||||
|
||||
### 📦 Dependencies & Compatibility
|
||||
|
||||
**Requires:**
|
||||
- Backend API v[X.X.X] or higher
|
||||
- [Other dependencies]
|
||||
|
||||
**Compatible with:**
|
||||
- [Previous version compatibility]
|
||||
|
||||
### 📥 Installation
|
||||
|
||||
[Download links and installation instructions]
|
||||
|
||||
### ⚠️ Known Issues & Workarounds
|
||||
|
||||
- Issue 1: [description] (Workaround: ...)
|
||||
|
||||
### 🔄 Migration Guide
|
||||
|
||||
[Steps for upgrading from previous version]
|
||||
|
||||
### 📞 Support
|
||||
|
||||
For issues: support@krow-workforce.com
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📍 Phase 3: CI/CD Integration (CodeMagic)
|
||||
|
||||
### Update CodeMagic for Automated Tagging (Optional)
|
||||
|
||||
Edit `codemagic.yaml` to automatically create tags on successful builds:
|
||||
|
||||
```yaml
|
||||
workflows:
|
||||
mobile-client-build:
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
# ... existing config ...
|
||||
|
||||
# Add this section
|
||||
on_success:
|
||||
- |
|
||||
if [ "$CI_BRANCH" = "main" ]; then
|
||||
VERSION=$(grep "^version:" apps/mobile/apps/client_app/pubspec.yaml | cut -d' ' -f2)
|
||||
git tag -a client-mobile/dev-${VERSION} \
|
||||
-m "Client Mobile ${VERSION} - Development build from CodeMagic"
|
||||
git push origin client-mobile/dev-${VERSION}
|
||||
fi
|
||||
```
|
||||
|
||||
(Optional - can be done manually initially)
|
||||
|
||||
---
|
||||
|
||||
## 📍 Phase 4: Create Release Documentation
|
||||
|
||||
### Copy Release Checklist Template
|
||||
|
||||
Create a file for release planning:
|
||||
|
||||
```bash
|
||||
mkdir -p docs/releases
|
||||
```
|
||||
|
||||
Create `docs/releases/RELEASE_TEMPLATE.md`:
|
||||
|
||||
```markdown
|
||||
# Release Plan: [Product] v[Version]
|
||||
|
||||
**Status**: Draft / In Progress / Completed
|
||||
**Target Date**: [Date]
|
||||
**Release Manager**: [Name]
|
||||
|
||||
## Scope
|
||||
|
||||
[Description of features/fixes in this release]
|
||||
|
||||
## Pre-Release Tasks (48h before)
|
||||
|
||||
- [ ] All PRs merged and code reviewed
|
||||
- [ ] All tests green (unit, integration, E2E)
|
||||
- [ ] No lint/type errors
|
||||
- [ ] Mobile builds succeed on CodeMagic
|
||||
- [ ] Performance benchmarks acceptable
|
||||
- [ ] Security scan passed
|
||||
- [ ] CHANGELOG.md updated with all changes
|
||||
- [ ] Documentation updated
|
||||
- [ ] Staging environment prepared for testing
|
||||
|
||||
## Release Day Tasks
|
||||
|
||||
- [ ] Create release branch: `release/[product]-v[version]`
|
||||
- [ ] Update version in all relevant files
|
||||
- [ ] Commit and push release branch
|
||||
- [ ] Create git tags (staging)
|
||||
- [ ] Deploy to staging environment
|
||||
- [ ] Run smoke tests
|
||||
- [ ] Get sign-off from product owner
|
||||
|
||||
## Post-Release Tasks (24h after)
|
||||
|
||||
- [ ] Monitor error logs
|
||||
- [ ] Verify all features work end-to-end
|
||||
- [ ] Performance is acceptable
|
||||
- [ ] Create production tags
|
||||
- [ ] Deploy to production
|
||||
- [ ] Final verification
|
||||
- [ ] Create GitHub Release page
|
||||
- [ ] Announce release to users
|
||||
|
||||
## Rollback Plan (if needed)
|
||||
|
||||
```
|
||||
Issue Found: [description]
|
||||
Severity: Critical / High / Medium
|
||||
Action: Rollback to v[previous-version]
|
||||
Hotfix: [version bump plan]
|
||||
```
|
||||
|
||||
## Outcomes
|
||||
|
||||
**Release Date**: [Actual date]
|
||||
**Status**: ✅ Successful / ⚠️ Issues / 🚫 Rolled back
|
||||
|
||||
[Additional notes]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📍 Phase 5: Team Training
|
||||
|
||||
### Create Runbook for Team
|
||||
|
||||
Share [RELEASE_WORKFLOW.md](./RELEASE_WORKFLOW.md) with your team
|
||||
|
||||
### Conduct Training Session
|
||||
|
||||
**Agenda (30 minutes):**
|
||||
1. Explain versioning strategy (5 min)
|
||||
2. Walk through release workflow (10 min)
|
||||
3. Demo: Create a test tag (10 min)
|
||||
4. Q&A (5 min)
|
||||
|
||||
### Sample Demo Commands
|
||||
|
||||
```bash
|
||||
# Everyone runs these to practice
|
||||
|
||||
# 1. See existing tags
|
||||
git tag -l
|
||||
|
||||
# 2. Create a test tag (won't push)
|
||||
git tag -a test/demo-v0.0.1 -m "Demo tag for training"
|
||||
|
||||
# 3. View tag details
|
||||
git show test/demo-v0.0.1
|
||||
|
||||
# 4. Delete test tag
|
||||
git tag -d test/demo-v0.0.1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📍 Phase 6: First Real Release
|
||||
|
||||
### Plan Your First Staging Release
|
||||
|
||||
Let's do: **Staff Mobile v0.2.0** (next development version)
|
||||
|
||||
### 1. Prepare Changes
|
||||
|
||||
```bash
|
||||
# Make your feature/fix commits normally
|
||||
git checkout main
|
||||
git pull origin main
|
||||
|
||||
# Create feature branches as usual
|
||||
git checkout -b feature/some-feature
|
||||
# ... make changes ...
|
||||
git commit -m "feat(staff-mobile): Add new feature"
|
||||
|
||||
git push origin feature/some-feature
|
||||
# Create PR, review, merge
|
||||
```
|
||||
|
||||
### 2. Create Release Branch
|
||||
|
||||
```bash
|
||||
# Start release
|
||||
git checkout main
|
||||
git pull origin main
|
||||
git checkout -b release/staff-mobile-v0.2.0
|
||||
```
|
||||
|
||||
### 3. Bump Version
|
||||
|
||||
```bash
|
||||
# Edit: apps/mobile/apps/staff_app/pubspec.yaml
|
||||
# Change: version: 0.1.0+5 → version: 0.2.0+6
|
||||
|
||||
nano apps/mobile/apps/staff_app/pubspec.yaml
|
||||
```
|
||||
|
||||
### 4. Update CHANGELOG
|
||||
|
||||
```bash
|
||||
nano CHANGELOG.md
|
||||
|
||||
# Add at top:
|
||||
# | 2026-03-05 | Staff Mobile 0.2.0 | Feature: [description] |
|
||||
```
|
||||
|
||||
### 5. Commit & Tag
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "chore(staff-mobile): bump version to 0.2.0"
|
||||
git push origin release/staff-mobile-v0.2.0
|
||||
|
||||
# Create and push tag
|
||||
git tag -a staff-mobile/staging-v0.2.0 -m "Staff Mobile v0.2.0 - Staging release"
|
||||
git push origin staff-mobile/staging-v0.2.0
|
||||
|
||||
# Verify
|
||||
git tag -l "staff-mobile/*" --sort=-version:refname
|
||||
```
|
||||
|
||||
### 6. Deploy & Test
|
||||
|
||||
```bash
|
||||
# Deploy to staging environment
|
||||
# (Use your deployment scripts or manual process)
|
||||
|
||||
# Run tests
|
||||
make test-mobile-staff
|
||||
|
||||
# Get team QA approval
|
||||
```
|
||||
|
||||
### 7. Promote to Production
|
||||
|
||||
```bash
|
||||
# Create production tag
|
||||
git tag -a staff-mobile/prod-v0.2.0 -m "Staff Mobile v0.2.0 - Production release"
|
||||
git push origin staff-mobile/prod-v0.2.0
|
||||
|
||||
# Deploy to production
|
||||
# (Use your deployment scripts)
|
||||
```
|
||||
|
||||
### 8. Create GitHub Release
|
||||
|
||||
1. Go to https://github.com/[your-org]/krow-workforce/releases
|
||||
2. Click "Draft a new release"
|
||||
3. Fill in:
|
||||
- Tag: `staff-mobile/prod-v0.2.0`
|
||||
- Title: `Staff Mobile v0.2.0`
|
||||
- Description: Copy from CHANGELOG
|
||||
- Add APK/AAB as attachments (if available)
|
||||
4. Click "Publish release"
|
||||
|
||||
---
|
||||
|
||||
## 📋 Communication Plan
|
||||
|
||||
### For Each Release
|
||||
|
||||
1. **Announcement** (release day)
|
||||
```
|
||||
📱 Staff Mobile v0.2.0 released!
|
||||
|
||||
Includes: [feature summary]
|
||||
Available: [iOS/Android app stores]
|
||||
```
|
||||
|
||||
2. **Status Updates** (during staging QA)
|
||||
```
|
||||
🔄 Staff Mobile v0.2.0 in staging for testing
|
||||
Expected production release: [date]
|
||||
```
|
||||
|
||||
3. **Post-Release** (24h after)
|
||||
```
|
||||
✅ Staff Mobile v0.2.0 now in production
|
||||
All systems normal. No issues reported.
|
||||
```
|
||||
|
||||
4. **If Issues**
|
||||
```
|
||||
⚠️ Staff Mobile v0.2.0 - Hotfix in progress
|
||||
Rollback to v0.1.0 - No impact to users
|
||||
ETA for fix: [time]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Troubleshooting
|
||||
|
||||
### Problem: Tag Already Exists
|
||||
|
||||
```bash
|
||||
# If you try to create a tag that exists:
|
||||
error: **/prod-v0.1.0 already exists
|
||||
|
||||
# Solution: Delete and recreate
|
||||
git tag -d staff-mobile/dev-v0.1.0
|
||||
git push origin --delete staff-mobile/dev-v0.1.0
|
||||
git tag -a staff-mobile/dev-v0.1.0 -m "New message"
|
||||
git push origin staff-mobile/dev-v0.1.0
|
||||
```
|
||||
|
||||
### Problem: Can't Push Tags
|
||||
|
||||
```bash
|
||||
# Error: remote permission denied
|
||||
|
||||
# Solution: Ensure you have push access
|
||||
git credential-osxkeychain erase host=github.com # Re-authenticate
|
||||
# Then try again
|
||||
git push origin --tags
|
||||
```
|
||||
|
||||
### Problem: Version Not Updated Everywhere
|
||||
|
||||
```bash
|
||||
# Verify all locations have same version
|
||||
grep -r "0.2.0" apps/mobile/apps/*/pubspec.yaml
|
||||
grep '"0.2.0"' apps/web/package.json
|
||||
grep '"0.2.0"' backend/*/package.json
|
||||
grep 'build_version: "0.2.0"' codemagic.yaml
|
||||
|
||||
# Update any missing locations
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ Validation Checklist
|
||||
|
||||
After implementing this strategy, verify:
|
||||
|
||||
- [ ] Initial dev tags created (v0.1.0 for all products)
|
||||
- [ ] GitHub branch protection configured for prod tags
|
||||
- [ ] Release template documented in repo
|
||||
- [ ] Team trained on release process
|
||||
- [ ] CHANGELOG.md in place and tracked
|
||||
- [ ] First staging release completed successfully
|
||||
- [ ] GitHub Release page created for first release
|
||||
- [ ] Communication plan working
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Next Steps
|
||||
|
||||
1. ✅ Review RELEASE_STRATEGY.md with team
|
||||
2. ✅ Complete Phase 1 setup (create initial tags)
|
||||
3. ✅ Configure GitHub (Phase 2)
|
||||
4. ⏳ First release (Staff Mobile v0.2.0) planned for [date]
|
||||
5. ⏳ Establish release cadence (weekly dev, bi-weekly staging, monthly prod)
|
||||
|
||||
---
|
||||
|
||||
## 📞 Questions?
|
||||
|
||||
Reference documents:
|
||||
- [RELEASE_STRATEGY.md](./RELEASE_STRATEGY.md) - Full strategy
|
||||
- [RELEASE_WORKFLOW.md](./RELEASE_WORKFLOW.md) - Step-by-step workflows
|
||||
- [CHANGELOG.md](./CHANGELOG.md) - Version history
|
||||
|
||||
---
|
||||
|
||||
**Created**: 2026-03-05
|
||||
**Status**: Ready for Implementation
|
||||
Reference in New Issue
Block a user