Krow/Krow-workspace
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
054852fcde7a4f8d607b31e74abd2b936f596762
Krow-workspace/RELEASE_INDEX.md
Achintha Isuru 085445e730 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.
2026-03-05 10:49:09 -05:00

412 lines
14 KiB
Markdown
Raw Blame History

# 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
Reference in New Issue View Git Blame Copy Permalink