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
parent faae6c07d5
commit 085445e730
13 changed files with 4650 additions and 2 deletions
--- a/RELEASE_INDEX.md
+++ b/RELEASE_INDEX.md
@@ -0,0 +1,411 @@
+# 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