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
267
RELEASE_QUICK_REFERENCE.md
Normal file
267
RELEASE_QUICK_REFERENCE.md
Normal file
@@ -0,0 +1,267 @@
|
||||
# Release Quick Reference Card
|
||||
|
||||
**Print this and pin it to your desk! 📌**
|
||||
|
||||
---
|
||||
|
||||
## ⚡ Quick Commands
|
||||
|
||||
### View All Tags
|
||||
```bash
|
||||
git tag -l "*" --sort=-version:refname
|
||||
```
|
||||
|
||||
### View Tags for One Product
|
||||
```bash
|
||||
git tag -l "staff-mobile/*" --sort=-version:refname
|
||||
```
|
||||
|
||||
### Create a Tag
|
||||
```bash
|
||||
git tag -a staff-mobile/dev-v0.2.0 -m "Staff Mobile v0.2.0"
|
||||
git push origin staff-mobile/dev-v0.2.0
|
||||
```
|
||||
|
||||
### See What's in a Tag
|
||||
```bash
|
||||
git show staff-mobile/prod-v0.1.0
|
||||
git log staff-mobile/prod-v0.1.0 -5 --oneline
|
||||
```
|
||||
|
||||
### Delete a Tag
|
||||
```bash
|
||||
git tag -d staff-mobile/dev-v0.1.0 # Local
|
||||
git push origin --delete staff-mobile/dev-v0.1.0 # Remote
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🏷️ Tag Naming Format
|
||||
|
||||
```
|
||||
<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! 🔖**
|
||||
Reference in New Issue
Block a user