saafe-redirection-flow 2.0.0

package/docs/RELEASE_GUIDE.md

@@ -0,0 +1,591 @@
+# 🚀 Saafe Redirection Flow - Complete Release Guide
+
+> **Version**: 1.0.0-stage.2  
+> **Last Updated**: June 23, 2025  
+> **Project**: Saafe Redirection Flow  
+
+## 📋 Table of Contents
+
+1. [Overview](#overview)
+2. [Quick Start](#quick-start)
+3. [Environment Configuration](#environment-configuration)
+4. [Release Process](#release-process)
+5. [Versioning Strategy](#versioning-strategy)
+6. [Branch Strategy](#branch-strategy)
+7. [Commit Conventions](#commit-conventions)
+8. [Commands Reference](#commands-reference)
+9. [Troubleshooting](#troubleshooting)
+10. [Examples](#examples)
+
+---
+
+## 🎯 Overview
+
+This project uses **Semantic Release** for automated version management, changelog generation, and deployment across multiple environments. The system automatically:
+
+- ✅ Analyzes commit messages using conventional commits
+- ✅ Determines semantic version bumps (patch/minor/major)
+- ✅ Generates changelogs automatically
+- ✅ Creates git tags for releases
+- ✅ Updates package.json versions
+- ✅ Manages environment-specific builds
+- ✅ Handles multi-environment deployment strategy
+
+### 🏗️ Architecture
+
+```
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│    Sandbox      │───▶│     Staging     │───▶│   Production    │
+│   (sandbox)     │    │     (stage)     │    │     (prod)      │
+│ v1.0.0-sandbox.1│    │ v1.0.0-stage.1  │    │     v1.0.1      │
+└─────────────────┘    └─────────────────┘    └─────────────────┘
+```
+
+---
+
+## ⚡ Quick Start
+
+### 🎬 Creating Your First Release
+
+```bash
+# 1. Make sure you're on the right branch
+git checkout stage  # or sandbox, main
+
+# 2. Create a release
+npm run release:real
+
+# 3. Build for deployment
+npm run build:stage  # or build:production, build:sandbox
+```
+
+### 🔄 Daily Workflow
+
+```bash
+# 1. Make changes using conventional commits
+git add .
+git commit -m "feat: add new authentication flow"
+
+# 2. Create release
+npm run release:real
+
+# 3. Deploy
+npm run build:stage
+```
+
+---
+
+## 🌍 Environment Configuration
+
+### 📁 Environment Files
+
+| File | Environment | API URL | Debug | Analytics |
+|------|-------------|---------|-------|-----------|
+| `.env.production` | Production | `https://api.saafe.in` | ❌ | ✅ |
+| `.env.stage` | Stage | `https://stage-api.saafe.in` | ✅ | ✅ |
+| `.env.sandbox` | Sandbox | `https://sandbox-api.saafe.in` | ✅ | ❌ |
+| `.env.development` | Development | `http://localhost:3000` | ✅ | ❌ |
+
+### 🔧 Environment Variables
+
+Each environment file contains:
+
+```bash
+# Environment identifier
+VITE_ENVIRONMENT=production
+
+# API Configuration
+VITE_API_BASE_URL=https://api.saafe.in
+
+# Application Settings
+VITE_DEBUG=false
+VITE_ANALYTICS_ENABLED=true
+
+# Build Configuration
+VITE_BASE_URL=/
+
+# Feature Flags
+VITE_FEATURE_DEBUG_PANEL=false
+VITE_FEATURE_TEST_MODE=false
+VITE_FEATURE_MOCK_DATA=false
+
+# Session Configuration
+VITE_SESSION_TIMEOUT=900000
+
+# PostHog Configuration
+VITE_PUBLIC_POSTHOG_HOST=
+VITE_PUBLIC_POSTHOG_KEY=
+```
+
+### 🎛️ Environment Detection
+
+The application automatically detects the environment through:
+
+1. **VITE_ENVIRONMENT** variable
+2. **Vite MODE** setting
+3. **Browser hostname** pattern matching
+4. **Defaults to production** if detection fails
+
+---
+
+## 🔄 Release Process
+
+### 🌟 Standard Release Flow
+
+#### **1. Sandbox Release**
+```bash
+git checkout sandbox
+# Make your changes with conventional commits
+git add .
+git commit -m "feat: add user authentication"
+npm run release:real
+npm run build:sandbox
+# Creates: v1.0.0-sandbox.X
+```
+
+#### **2. Stage Release**
+```bash
+git checkout stage
+git merge sandbox
+npm run release:real
+npm run build:stage
+# Creates: v1.0.0-stage.X
+```
+
+#### **3. Production Release**
+```bash
+git checkout prod
+git merge stage
+npm run release:real
+npm run build:production
+# Creates: v1.0.1 (production version bump!)
+```
+
+### 🎯 Release Types
+
+| Release Type | Triggers | Version Change | Example |
+|-------------|----------|----------------|---------|
+| **Patch** | `fix:` commits | `1.0.0` → `1.0.1` | Bug fixes |
+| **Minor** | `feat:` commits | `1.0.0` → `1.1.0` | New features |
+| **Major** | `BREAKING CHANGE:` | `1.0.0` → `2.0.0` | Breaking changes |
+
+---
+
+## 📊 Versioning Strategy
+
+### 🏷️ Version Format
+
+#### **Production Releases (main branch)**
+```
+v1.0.0     # First release
+v1.0.1     # Patch release
+v1.1.0     # Minor release
+v2.0.0     # Major release
+```
+
+#### **Prerelease Branches**
+```
+v1.0.0-stage.1         # First stage release
+v1.0.0-stage.2         # Second stage release
+v1.0.0-sandbox.1       # First sandbox release
+```
+
+### 🔄 Version Progression
+
+```
+sandbox:        1.0.0-sandbox.1 → 1.0.0-sandbox.2
+         ↓
+stage:          1.0.0-stage.1 → 1.0.0-stage.2
+         ↓
+prod:           1.0.1 ← Production version finally bumps!
+         ↓
+stage:          1.0.1-stage.1 ← Based on new production version
+```
+
+### 📈 Current Release Status
+
+```
+✅ sandbox:        v1.0.0-sandbox.1
+✅ stage:          v1.0.0-stage.2
+⏳ prod:           Ready for v1.0.1
+```
+
+---
+
+## 🌳 Branch Strategy
+
+### 📋 Branch Configuration
+
+```json
+{
+  "branches": [
+    "prod",                    // Production releases
+    {
+      "name": "stage",         // Stage prereleases
+      "prerelease": "stage"
+    },
+    {
+      "name": "sandbox",       // Sandbox prereleases
+      "prerelease": "sandbox"
+    }
+  ]
+}
+```
+
+### 🎯 Branch Purposes
+
+| Branch | Purpose | Release Type | Deploy Target |
+|--------|---------|--------------|---------------|
+| **prod** | Production-ready code | Production | Production servers |
+| **stage** | Release candidate testing | Prerelease | Staging environment |
+| **sandbox** | Integration testing | Prerelease | Sandbox environment |
+
+### 🔄 Merge Strategy
+
+```
+sandbox → stage → prod
+     ↓      ↓       ↓
+Integration  QA   Production
+```
+
+---
+
+## 📝 Commit Conventions
+
+### 🎯 Commit Message Format
+
+```
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+### 📋 Commit Types
+
+| Type | Description | Version Bump | Example |
+|------|-------------|--------------|---------|
+| `feat` | New feature | Minor | `feat: add user login` |
+| `fix` | Bug fix | Patch | `fix: resolve login issue` |
+| `docs` | Documentation | None | `docs: update README` |
+| `style` | Code style changes | None | `style: format code` |
+| `refactor` | Code refactoring | None | `refactor: simplify auth logic` |
+| `test` | Adding tests | None | `test: add login tests` |
+| `chore` | Maintenance tasks | None | `chore: update dependencies` |
+
+### 🚨 Breaking Changes
+
+```bash
+feat!: redesign authentication API
+
+BREAKING CHANGE: The authentication API has been completely redesigned.
+Migration guide available in MIGRATION.md
+```
+
+### ✅ Good Commit Examples
+
+```bash
+✅ feat: add two-factor authentication
+✅ fix: resolve memory leak in data processing
+✅ feat(auth): implement OAuth2 integration
+✅ fix(ui): correct button alignment on mobile
+✅ docs: add API documentation for user endpoints
+```
+
+### ❌ Bad Commit Examples
+
+```bash
+❌ update stuff
+❌ fixes
+❌ WIP
+❌ asdf
+❌ more changes
+```
+
+---
+
+## 🛠️ Commands Reference
+
+### 🚀 Release Commands
+
+```bash
+# Real releases (recommended)
+npm run release:real         # Create actual release with --no-ci flag
+
+# Test releases
+npm run release:dry          # Dry run - shows what would happen
+npm run release              # Original command (may run in dry-run mode)
+```
+
+### 🏗️ Build Commands
+
+```bash
+# Environment-specific builds
+npm run build:production     # Production build
+npm run build:stage         # Stage build
+npm run build:sandbox       # Sandbox build
+
+# Build all environments
+npm run build:all           # Builds production, stage, and sandbox
+```
+
+### 👀 Preview Commands
+
+```bash
+# Environment-specific previews
+npm run preview:production   # Preview production build
+npm run preview:stage       # Preview stage build
+npm run preview:sandbox     # Preview sandbox build
+```
+
+### 📊 Information Commands
+
+```bash
+# Version information
+npm run version:check       # Show current version
+git tag --list             # Show all release tags
+git tag --list | grep stage # Show stage-specific tags
+
+# Environment information
+npm run env:check          # Show environment variables
+npm run env:list           # List all .env files
+ls -la .env*              # Show environment files with details
+```
+
+### 📋 Git Commands
+
+```bash
+# Tag management
+git tag --list                    # List all tags
+git tag --sort=-version:refname   # List tags sorted by version
+git show v1.0.0-stage.2          # Show specific tag details
+
+# Commit history
+git log --oneline -10             # Recent commits
+git log --oneline --grep="feat"   # Filter by commit type
+git log --oneline --decorate      # Show commits with tags
+```
+
+---
+
+## 🔧 Troubleshooting
+
+### ❓ Common Issues
+
+#### **1. Release Running in Dry-Run Mode**
+
+**Problem**: Release shows "running in dry-run mode"
+```bash
+⚠  This run was not triggered in a known CI environment, running in dry-run mode.
+```
+
+**Solution**:
+```bash
+# Use the real release command
+npm run release:real
+
+# Or force with environment variable
+CI=true npm run release
+```
+
+#### **2. No Version Bump on Prerelease Branch**
+
+**Problem**: Version shows `1.0.0-stage.2` instead of `1.0.1-stage.1`
+
+**Solution**: This is **expected behavior**. Main version only bumps on `main` branch.
+```bash
+# To get main version bump:
+git checkout main
+git merge stage
+npm run release:real  # This will create v1.0.1
+```
+
+#### **3. No Commits Found**
+
+**Problem**: "No commits found since last release"
+
+**Solution**: Make sure you have new conventional commits since the last release.
+```bash
+# Check recent commits
+git log --oneline -5
+
+# Make a new commit
+git add .
+git commit -m "feat: add new feature"
+npm run release:real
+```
+
+#### **4. Build Failures**
+
+**Problem**: TypeScript errors during build
+
+**Solution**: Fix TypeScript errors or build without strict checking:
+```bash
+# Skip TypeScript checking temporarily
+npx vite build --mode production
+
+# Fix errors in codebase
+npm run lint
+# Fix the reported issues
+```
+
+#### **5. Wrong Environment Variables**
+
+**Problem**: App shows wrong environment or API URL
+
+**Solution**: Check environment file loading:
+```bash
+# Verify environment files exist
+npm run env:list
+
+# Check current environment detection
+npm run env:check
+
+# Check vite config
+cat vite.config.ts
+```
+
+### 🔍 Debug Commands
+
+```bash
+# Debug semantic release
+npm run semantic-release -- --dry-run --debug
+
+# Debug environment loading
+node -e "console.log(require('vite').loadEnv('production', process.cwd()))"
+
+# Debug build process
+npm run build:stage -- --debug
+```
+
+---
+
+## 📚 Examples
+
+### 🎬 Example: Feature Development to Production
+
+```bash
+# 1. Start in sandbox
+git checkout sandbox
+git add .
+git commit -m "feat: implement user dashboard"
+npm run release:real
+# Creates: v1.0.0-sandbox.1
+
+# 2. Test in sandbox
+npm run build:sandbox
+
+# 3. Stage for QA
+git checkout stage
+git merge sandbox
+npm run release:real
+npm run build:stage
+# Creates: v1.0.0-stage.1
+
+# 4. Deploy to production
+git checkout prod
+git merge stage
+npm run release:real
+npm run build:production
+# Creates: v1.0.1 🎉
+```
+
+### 🐛 Example: Hotfix Release
+
+```bash
+# 1. Create hotfix on prod
+git checkout prod
+git add .
+git commit -m "fix: resolve critical security issue"
+npm run release:real
+# Creates: v1.0.2
+
+# 2. Merge back to development branches
+git checkout stage
+git merge prod
+git checkout sandbox
+git merge prod
+```
+
+### 🔄 Example: Multiple Features
+
+```bash
+# Feature A
+git checkout sandbox
+git commit -m "feat: add user authentication"
+npm run release:real
+# Creates: v1.0.0-sandbox.1
+
+# Feature B
+git commit -m "feat: add password reset"
+npm run release:real
+# Creates: v1.0.0-sandbox.2
+
+# Deploy both features
+git checkout stage
+git merge sandbox
+npm run release:real
+# Creates: v1.0.0-stage.1 (includes both features)
+```
+
+### 📊 Example: Viewing Release History
+
+```bash
+# View all releases
+git tag --list --sort=-version:refname
+
+# View specific branch releases
+git tag --list | grep stage
+git tag --list | grep sandbox
+
+# View changelog
+cat CHANGELOG.md
+
+# View specific release details
+git show v1.0.0-stage.2
+```
+
+---
+
+## 📞 Support & Resources
+
+### 🔗 Useful Links
+
+- **Conventional Commits**: https://conventionalcommits.org/
+- **Semantic Release**: https://semantic-release.gitbook.io/semantic-release/
+- **Semantic Versioning**: https://semver.org/
+
+### 📋 Quick Reference Card
+
+```bash
+# Daily commands
+npm run release:real         # Create release
+npm run version:check        # Check version
+npm run build:stage         # Build for staging
+
+# Emergency commands
+npm run release:dry         # Test release
+git tag --list             # List all versions
+git log --oneline -5       # Recent commits
+```
+
+### 🆘 Getting Help
+
+1. **Check this documentation** first
+2. **Run debug commands** to gather information
+3. **Check recent commits** for conventional format
+4. **Verify environment files** are correct
+5. **Contact the development team** if issues persist
+
+---
+
+## 📅 Changelog
+
+| Date | Version | Changes |
+|------|---------|---------|
+| 2025-06-23 | 1.0.0 | Initial release documentation |
+| 2025-06-23 | 1.0.0-stage.2 | Current version with all features |
+
+---
+
+**🎉 Happy Releasing!**