Back to skills
SkillHub ClubShip Full StackFull Stack
release-manager
Release Manager
Packaged view
This page reorganizes the original catalog entry around fit, installability, and workflow context first. The original raw source lives below.
Stars
5,425
Hot score
99
Updated
March 20, 2026
Overall rating
C4.0
Composite score
4.0
Best-practice grade
C64.8
Install command
npx @skill-hub/cli install alirezarezvani-claude-skills-release-manager
Repository
Best for
Primary workflow: Ship Full Stack.
Technical facets: Full Stack.
Target audience: everyone.
License: Unknown.
Original source
Catalog source: SkillHub Club.
Repository owner: alirezarezvani.
This is still a mirrored public skill entry. Review the repository before installing into production workflows.
What it helps with
- Install release-manager into Claude Code, Codex CLI, Gemini CLI, or OpenCode workflows
- Review https://github.com/alirezarezvani/claude-skills before adding release-manager to shared team environments
- Use release-manager for development workflows
Works across
Claude CodeCodex CLIGemini CLIOpenCode
Favorites: 0.
Sub-skills: 0.
Aggregator: No.
Original source / Raw SKILL.md
--- name: "release-manager" description: "Release Manager" --- # Release Manager **Tier:** POWERFUL **Category:** Engineering **Domain:** Software Release Management & DevOps ## Overview The Release Manager skill provides comprehensive tools and knowledge for managing software releases end-to-end. From parsing conventional commits to generating changelogs, determining version bumps, and orchestrating release processes, this skill ensures reliable, predictable, and well-documented software releases. ## Core Capabilities - **Automated Changelog Generation** from git history using conventional commits - **Semantic Version Bumping** based on commit analysis and breaking changes - **Release Readiness Assessment** with comprehensive checklists and validation - **Release Planning & Coordination** with stakeholder communication templates - **Rollback Planning** with automated recovery procedures - **Hotfix Management** for emergency releases - **Feature Flag Integration** for progressive rollouts ## Key Components ### Scripts 1. **changelog_generator.py** - Parses git logs and generates structured changelogs 2. **version_bumper.py** - Determines correct version bumps from conventional commits 3. **release_planner.py** - Assesses release readiness and generates coordination plans ### Documentation - Comprehensive release management methodology - Conventional commits specification and examples - Release workflow comparisons (Git Flow, Trunk-based, GitHub Flow) - Hotfix procedures and emergency response protocols ## Release Management Methodology ### Semantic Versioning (SemVer) Semantic Versioning follows the MAJOR.MINOR.PATCH format where: - **MAJOR** version when you make incompatible API changes - **MINOR** version when you add functionality in a backwards compatible manner - **PATCH** version when you make backwards compatible bug fixes #### Pre-release Versions Pre-release versions are denoted by appending a hyphen and identifiers: - `1.0.0-alpha.1` - Alpha releases for early testing - `1.0.0-beta.2` - Beta releases for wider testing - `1.0.0-rc.1` - Release candidates for final validation #### Version Precedence Version precedence is determined by comparing each identifier: 1. `1.0.0-alpha` < `1.0.0-alpha.1` < `1.0.0-alpha.beta` < `1.0.0-beta` 2. `1.0.0-beta` < `1.0.0-beta.2` < `1.0.0-beta.11` < `1.0.0-rc.1` 3. `1.0.0-rc.1` < `1.0.0` ### Conventional Commits Conventional Commits provide a structured format for commit messages that enables automated tooling: #### Format ``` <type>[optional scope]: <description> [optional body] [optional footer(s)] ``` #### Types - **feat**: A new feature (correlates with MINOR version bump) - **fix**: A bug fix (correlates with PATCH version bump) - **docs**: Documentation only changes - **style**: Changes that do not affect the meaning of the code - **refactor**: A code change that neither fixes a bug nor adds a feature - **perf**: A code change that improves performance - **test**: Adding missing tests or correcting existing tests - **chore**: Changes to the build process or auxiliary tools - **ci**: Changes to CI configuration files and scripts - **build**: Changes that affect the build system or external dependencies - **breaking**: Introduces a breaking change (correlates with MAJOR version bump) #### Examples ``` feat(user-auth): add OAuth2 integration fix(api): resolve race condition in user creation docs(readme): update installation instructions feat!: remove deprecated payment API BREAKING CHANGE: The legacy payment API has been removed ``` ### Automated Changelog Generation Changelogs are automatically generated from conventional commits, organized by: #### Structure ```markdown # Changelog ## [Unreleased] ### Added ### Changed ### Deprecated ### Removed ### Fixed ### Security ## [1.2.0] - 2024-01-15 ### Added - OAuth2 authentication support (#123) - User preference dashboard (#145) ### Fixed - Race condition in user creation (#134) - Memory leak in image processing (#156) ### Breaking Changes - Removed legacy payment API ``` #### Grouping Rules - **Added** for new features (feat) - **Fixed** for bug fixes (fix) - **Changed** for changes in existing functionality - **Deprecated** for soon-to-be removed features - **Removed** for now removed features - **Security** for vulnerability fixes #### Metadata Extraction - Link to pull requests and issues: `(#123)` - Breaking changes highlighted prominently - Scope-based grouping: `auth:`, `api:`, `ui:` - Co-authored-by for contributor recognition ### Version Bump Strategies Version bumps are determined by analyzing commits since the last release: #### Automatic Detection Rules 1. **MAJOR**: Any commit with `BREAKING CHANGE` or `!` after type 2. **MINOR**: Any `feat` type commits without breaking changes 3. **PATCH**: `fix`, `perf`, `security` type commits 4. **NO BUMP**: `docs`, `style`, `test`, `chore`, `ci`, `build` only #### Pre-release Handling ```python # Alpha: 1.0.0-alpha.1 → 1.0.0-alpha.2 # Beta: 1.0.0-alpha.5 → 1.0.0-beta.1 # RC: 1.0.0-beta.3 → 1.0.0-rc.1 # Release: 1.0.0-rc.2 → 1.0.0 ``` #### Multi-package Considerations For monorepos with multiple packages: - Analyze commits affecting each package independently - Support scoped version bumps: `@scope/[email protected]` - Generate coordinated release plans across packages ### Release Branch Workflows #### Git Flow ``` main (production) ← release/1.2.0 ← develop ← feature/login ← hotfix/critical-fix ``` **Advantages:** - Clear separation of concerns - Stable main branch - Parallel feature development - Structured release process **Process:** 1. Create release branch from develop: `git checkout -b release/1.2.0 develop` 2. Finalize release (version bump, changelog) 3. Merge to main and develop 4. Tag release: `git tag v1.2.0` 5. Deploy from main #### Trunk-based Development ``` main ← feature/login (short-lived) ← feature/payment (short-lived) ← hotfix/critical-fix ``` **Advantages:** - Simplified workflow - Faster integration - Reduced merge conflicts - Continuous integration friendly **Process:** 1. Short-lived feature branches (1-3 days) 2. Frequent commits to main 3. Feature flags for incomplete features 4. Automated testing gates 5. Deploy from main with feature toggles #### GitHub Flow ``` main ← feature/login ← hotfix/critical-fix ``` **Advantages:** - Simple and lightweight - Fast deployment cycle - Good for web applications - Minimal overhead **Process:** 1. Create feature branch from main 2. Regular commits and pushes 3. Open pull request when ready 4. Deploy from feature branch for testing 5. Merge to main and deploy ### Feature Flag Integration Feature flags enable safe, progressive rollouts: #### Types of Feature Flags - **Release flags**: Control feature visibility in production - **Experiment flags**: A/B testing and gradual rollouts - **Operational flags**: Circuit breakers and performance toggles - **Permission flags**: Role-based feature access #### Implementation Strategy ```python # Progressive rollout example if feature_flag("new_payment_flow", user_id): return new_payment_processor.process(payment) else: return legacy_payment_processor.process(payment) ``` #### Release Coordination 1. Deploy code with feature behind flag (disabled) 2. Gradually enable for percentage of users 3. Monitor metrics and error rates 4. Full rollout or quick rollback based on data 5. Remove flag in subsequent release ### Release Readiness Checklists #### Pre-Release Validation - [ ] All planned features implemented and tested - [ ] Breaking changes documented with migration guide - [ ] API documentation updated - [ ] Database migrations tested - [ ] Security review completed for sensitive changes - [ ] Performance testing passed thresholds - [ ] Internationalization strings updated - [ ] Third-party integrations validated #### Quality Gates - [ ] Unit test coverage ≥ 85% - [ ] Integration tests passing - [ ] End-to-end tests passing - [ ] Static analysis clean - [ ] Security scan passed - [ ] Dependency audit clean - [ ] Load testing completed #### Documentation Requirements - [ ] CHANGELOG.md updated - [ ] README.md reflects new features - [ ] API documentation generated - [ ] Migration guide written for breaking changes - [ ] Deployment notes prepared - [ ] Rollback procedure documented #### Stakeholder Approvals - [ ] Product Manager sign-off - [ ] Engineering Lead approval - [ ] QA validation complete - [ ] Security team clearance - [ ] Legal review (if applicable) - [ ] Compliance check (if regulated) ### Deployment Coordination #### Communication Plan **Internal Stakeholders:** - Engineering team: Technical changes and rollback procedures - Product team: Feature descriptions and user impact - Support team: Known issues and troubleshooting guides - Sales team: Customer-facing changes and talking points **External Communication:** - Release notes for users - API changelog for developers - Migration guide for breaking changes - Downtime notifications if applicable #### Deployment Sequence 1. **Pre-deployment** (T-24h): Final validation, freeze code 2. **Database migrations** (T-2h): Run and validate schema changes 3. **Blue-green deployment** (T-0): Switch traffic gradually 4. **Post-deployment** (T+1h): Monitor metrics and logs 5. **Rollback window** (T+4h): Decision point for rollback #### Monitoring & Validation - Application health checks - Error rate monitoring - Performance metrics tracking - User experience monitoring - Business metrics validation - Third-party service integration health ### Hotfix Procedures Hotfixes address critical production issues requiring immediate deployment: #### Severity Classification **P0 - Critical**: Complete system outage, data loss, security breach - **SLA**: Fix within 2 hours - **Process**: Emergency deployment, all hands on deck - **Approval**: Engineering Lead + On-call Manager **P1 - High**: Major feature broken, significant user impact - **SLA**: Fix within 24 hours - **Process**: Expedited review and deployment - **Approval**: Engineering Lead + Product Manager **P2 - Medium**: Minor feature issues, limited user impact - **SLA**: Fix in next release cycle - **Process**: Normal review process - **Approval**: Standard PR review #### Emergency Response Process 1. **Incident declaration**: Page on-call team 2. **Assessment**: Determine severity and impact 3. **Hotfix branch**: Create from last stable release 4. **Minimal fix**: Address root cause only 5. **Expedited testing**: Automated tests + manual validation 6. **Emergency deployment**: Deploy to production 7. **Post-incident**: Root cause analysis and prevention ### Rollback Planning Every release must have a tested rollback plan: #### Rollback Triggers - **Error rate spike**: >2x baseline within 30 minutes - **Performance degradation**: >50% latency increase - **Feature failures**: Core functionality broken - **Security incident**: Vulnerability exploited - **Data corruption**: Database integrity compromised #### Rollback Types **Code Rollback:** - Revert to previous Docker image - Database-compatible code changes only - Feature flag disable preferred over code rollback **Database Rollback:** - Only for non-destructive migrations - Data backup required before migration - Forward-only migrations preferred (add columns, not drop) **Infrastructure Rollback:** - Blue-green deployment switch - Load balancer configuration revert - DNS changes (longer propagation time) #### Automated Rollback ```python # Example rollback automation def monitor_deployment(): if error_rate() > THRESHOLD: alert_oncall("Error rate spike detected") if auto_rollback_enabled(): execute_rollback() ``` ### Release Metrics & Analytics #### Key Performance Indicators - **Lead Time**: From commit to production - **Deployment Frequency**: Releases per week/month - **Mean Time to Recovery**: From incident to resolution - **Change Failure Rate**: Percentage of releases causing incidents #### Quality Metrics - **Rollback Rate**: Percentage of releases rolled back - **Hotfix Rate**: Hotfixes per regular release - **Bug Escape Rate**: Production bugs per release - **Time to Detection**: How quickly issues are identified #### Process Metrics - **Review Time**: Time spent in code review - **Testing Time**: Automated + manual testing duration - **Approval Cycle**: Time from PR to merge - **Release Preparation**: Time spent on release activities ### Tool Integration #### Version Control Systems - **Git**: Primary VCS with conventional commit parsing - **GitHub/GitLab**: Pull request automation and CI/CD - **Bitbucket**: Pipeline integration and deployment gates #### CI/CD Platforms - **Jenkins**: Pipeline orchestration and deployment automation - **GitHub Actions**: Workflow automation and release publishing - **GitLab CI**: Integrated pipelines with environment management - **CircleCI**: Container-based builds and deployments #### Monitoring & Alerting - **DataDog**: Application performance monitoring - **New Relic**: Error tracking and performance insights - **Sentry**: Error aggregation and release tracking - **PagerDuty**: Incident response and escalation #### Communication Platforms - **Slack**: Release notifications and coordination - **Microsoft Teams**: Stakeholder communication - **Email**: External customer notifications - **Status Pages**: Public incident communication ## Best Practices ### Release Planning 1. **Regular cadence**: Establish predictable release schedule 2. **Feature freeze**: Lock changes 48h before release 3. **Risk assessment**: Evaluate changes for potential impact 4. **Stakeholder alignment**: Ensure all teams are prepared ### Quality Assurance 1. **Automated testing**: Comprehensive test coverage 2. **Staging environment**: Production-like testing environment 3. **Canary releases**: Gradual rollout to subset of users 4. **Monitoring**: Proactive issue detection ### Communication 1. **Clear timelines**: Communicate schedules early 2. **Regular updates**: Status reports during release process 3. **Issue transparency**: Honest communication about problems 4. **Post-mortems**: Learn from incidents and improve ### Automation 1. **Reduce manual steps**: Automate repetitive tasks 2. **Consistent process**: Same steps every time 3. **Audit trails**: Log all release activities 4. **Self-service**: Enable teams to deploy safely ## Common Anti-patterns ### Process Anti-patterns - **Manual deployments**: Error-prone and inconsistent - **Last-minute changes**: Risk introduction without proper testing - **Skipping testing**: Deploying without validation - **Poor communication**: Stakeholders unaware of changes ### Technical Anti-patterns - **Monolithic releases**: Large, infrequent releases with high risk - **Coupled deployments**: Services that must be deployed together - **No rollback plan**: Unable to quickly recover from issues - **Environment drift**: Production differs from staging ### Cultural Anti-patterns - **Blame culture**: Fear of making changes or reporting issues - **Hero culture**: Relying on individuals instead of process - **Perfectionism**: Delaying releases for minor improvements - **Risk aversion**: Avoiding necessary changes due to fear ## Getting Started 1. **Assessment**: Evaluate current release process and pain points 2. **Tool setup**: Configure scripts for your repository 3. **Process definition**: Choose appropriate workflow for your team 4. **Automation**: Implement CI/CD pipelines and quality gates 5. **Training**: Educate team on new processes and tools 6. **Monitoring**: Set up metrics and alerting for releases 7. **Iteration**: Continuously improve based on feedback and metrics The Release Manager skill transforms chaotic deployments into predictable, reliable releases that build confidence across your entire organization. --- ## Skill Companion Files > Additional files collected from the skill directory layout. ### README.md ```markdown # Release Manager A comprehensive release management toolkit for automating changelog generation, version bumping, and release planning based on conventional commits and industry best practices. ## Overview The Release Manager skill provides three powerful Python scripts and comprehensive documentation for managing software releases: 1. **changelog_generator.py** - Generate structured changelogs from git history 2. **version_bumper.py** - Determine correct semantic version bumps 3. **release_planner.py** - Assess release readiness and generate coordination plans ## Quick Start ### Prerequisites - Python 3.7+ - Git repository with conventional commit messages - No external dependencies required (uses only Python standard library) ### Basic Usage ```bash # Generate changelog from recent commits git log --oneline --since="1 month ago" | python changelog_generator.py # Determine version bump from commits since last tag git log --oneline $(git describe --tags --abbrev=0)..HEAD | python version_bumper.py -c "1.2.3" # Assess release readiness python release_planner.py --input assets/sample_release_plan.json ``` ## Scripts Reference ### changelog_generator.py Parses conventional commits and generates structured changelogs in multiple formats. **Input Options:** - Git log text (oneline or full format) - JSON array of commits - Stdin or file input **Output Formats:** - Markdown (Keep a Changelog format) - JSON structured data - Both with release statistics ```bash # From git log (recommended) git log --oneline --since="last release" | python changelog_generator.py \ --version "2.1.0" \ --date "2024-01-15" \ --base-url "https://github.com/yourorg/yourrepo" # From JSON file python changelog_generator.py \ --input assets/sample_commits.json \ --input-format json \ --format both \ --summary # With custom output git log --format="%h %s" v1.0.0..HEAD | python changelog_generator.py \ --version "1.1.0" \ --output CHANGELOG_DRAFT.md ``` **Features:** - Parses conventional commit types (feat, fix, docs, etc.) - Groups commits by changelog categories (Added, Fixed, Changed, etc.) - Extracts issue references (#123, fixes #456) - Identifies breaking changes - Links to commits and PRs - Generates release summary statistics ### version_bumper.py Analyzes commits to determine semantic version bumps according to conventional commits. **Bump Rules:** - **MAJOR:** Breaking changes (`feat!:` or `BREAKING CHANGE:`) - **MINOR:** New features (`feat:`) - **PATCH:** Bug fixes (`fix:`, `perf:`, `security:`) - **NONE:** Documentation, tests, chores only ```bash # Basic version bump determination git log --oneline v1.2.3..HEAD | python version_bumper.py --current-version "1.2.3" # With pre-release version python version_bumper.py \ --current-version "1.2.3" \ --prerelease alpha \ --input assets/sample_commits.json \ --input-format json # Include bump commands and file updates git log --oneline $(git describe --tags --abbrev=0)..HEAD | \ python version_bumper.py \ --current-version "$(git describe --tags --abbrev=0)" \ --include-commands \ --include-files \ --analysis ``` **Features:** - Supports pre-release versions (alpha, beta, rc) - Generates bump commands for npm, Python, Rust, Git - Provides file update snippets - Detailed commit analysis and categorization - Custom rules for specific commit types - JSON and text output formats ### release_planner.py Assesses release readiness and generates comprehensive release coordination plans. **Input:** JSON release plan with features, quality gates, and stakeholders ```bash # Assess release readiness python release_planner.py --input assets/sample_release_plan.json # Generate full release package python release_planner.py \ --input release_plan.json \ --output-format markdown \ --include-checklist \ --include-communication \ --include-rollback \ --output release_report.md ``` **Features:** - Feature readiness assessment with approval tracking - Quality gate validation and reporting - Stakeholder communication planning - Rollback procedure generation - Risk analysis and timeline assessment - Customizable test coverage thresholds - Multiple output formats (text, JSON, Markdown) ## File Structure ``` release-manager/ ├── SKILL.md # Comprehensive methodology guide ├── README.md # This file ├── changelog_generator.py # Changelog generation script ├── version_bumper.py # Version bump determination ├── release_planner.py # Release readiness assessment ├── references/ # Reference documentation │ ├── conventional-commits-guide.md # Conventional commits specification │ ├── release-workflow-comparison.md # Git Flow vs GitHub Flow vs Trunk-based │ └── hotfix-procedures.md # Emergency release procedures ├── assets/ # Sample data for testing │ ├── sample_git_log.txt # Sample git log output │ ├── sample_git_log_full.txt # Detailed git log format │ ├── sample_commits.json # JSON commit data │ └── sample_release_plan.json # Release plan template └── expected_outputs/ # Example script outputs ├── changelog_example.md # Expected changelog format ├── version_bump_example.txt # Version bump output └── release_readiness_example.txt # Release assessment report ``` ## Integration Examples ### CI/CD Pipeline Integration ```yaml # .github/workflows/release.yml name: Automated Release on: push: branches: [main] jobs: release: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 with: fetch-depth: 0 # Need full history - name: Determine version bump id: version run: | CURRENT=$(git describe --tags --abbrev=0) git log --oneline $CURRENT..HEAD | \ python scripts/version_bumper.py -c $CURRENT --output-format json > bump.json echo "new_version=$(jq -r '.recommended_version' bump.json)" >> $GITHUB_OUTPUT - name: Generate changelog run: | git log --oneline ${{ steps.version.outputs.current_version }}..HEAD | \ python scripts/changelog_generator.py \ --version "${{ steps.version.outputs.new_version }}" \ --base-url "https://github.com/${{ github.repository }}" \ --output CHANGELOG_ENTRY.md - name: Create release uses: actions/create-release@v1 with: tag_name: v${{ steps.version.outputs.new_version }} release_name: Release ${{ steps.version.outputs.new_version }} body_path: CHANGELOG_ENTRY.md ``` ### Git Hooks Integration ```bash #!/bin/bash # .git/hooks/pre-commit # Validate conventional commit format commit_msg_file=$1 commit_msg=$(cat $commit_msg_file) # Simple validation (more sophisticated validation available in commitlint) if ! echo "$commit_msg" | grep -qE "^(feat|fix|docs|style|refactor|test|chore|perf|ci|build)(\(.+\))?(!)?:"; then echo "❌ Commit message doesn't follow conventional commits format" echo "Expected: type(scope): description" echo "Examples:" echo " feat(auth): add OAuth2 integration" echo " fix(api): resolve race condition" echo " docs: update installation guide" exit 1 fi echo "✅ Commit message format is valid" ``` ### Release Planning Automation ```python #!/usr/bin/env python3 # generate_release_plan.py - Automatically generate release plans from project management tools import json import requests from datetime import datetime, timedelta def generate_release_plan_from_github(repo, milestone): """Generate release plan from GitHub milestone and PRs.""" # Fetch milestone details milestone_url = f"https://api.github.com/repos/{repo}/milestones/{milestone}" milestone_data = requests.get(milestone_url).json() # Fetch associated issues/PRs issues_url = f"https://api.github.com/repos/{repo}/issues?milestone={milestone}&state=all" issues = requests.get(issues_url).json() release_plan = { "release_name": milestone_data["title"], "version": "TBD", # Fill in manually or extract from milestone "target_date": milestone_data["due_on"], "features": [] } for issue in issues: if issue.get("pull_request"): # It's a PR feature = { "id": f"GH-{issue['number']}", "title": issue["title"], "description": issue["body"][:200] + "..." if len(issue["body"]) > 200 else issue["body"], "type": "feature", # Could be parsed from labels "assignee": issue["assignee"]["login"] if issue["assignee"] else "", "status": "ready" if issue["state"] == "closed" else "in_progress", "pull_request_url": issue["pull_request"]["html_url"], "issue_url": issue["html_url"], "risk_level": "medium", # Could be parsed from labels "qa_approved": "qa-approved" in [label["name"] for label in issue["labels"]], "pm_approved": "pm-approved" in [label["name"] for label in issue["labels"]] } release_plan["features"].append(feature) return release_plan # Usage if __name__ == "__main__": plan = generate_release_plan_from_github("yourorg/yourrepo", "5") with open("release_plan.json", "w") as f: json.dump(plan, f, indent=2) print("Generated release_plan.json") print("Run: python release_planner.py --input release_plan.json") ``` ## Advanced Usage ### Custom Commit Type Rules ```bash # Define custom rules for version bumping python version_bumper.py \ --current-version "1.2.3" \ --custom-rules '{"security": "patch", "breaking": "major"}' \ --ignore-types "docs,style,test" ``` ### Multi-repository Release Coordination ```bash #!/bin/bash # multi_repo_release.sh - Coordinate releases across multiple repositories repos=("frontend" "backend" "mobile" "docs") base_version="2.1.0" for repo in "${repos[@]}"; do echo "Processing $repo..." cd "$repo" # Generate changelog for this repo git log --oneline --since="1 month ago" | \ python ../scripts/changelog_generator.py \ --version "$base_version" \ --output "CHANGELOG_$repo.md" # Determine version bump git log --oneline $(git describe --tags --abbrev=0)..HEAD | \ python ../scripts/version_bumper.py \ --current-version "$(git describe --tags --abbrev=0)" > "VERSION_$repo.txt" cd .. done echo "Generated changelogs and version recommendations for all repositories" ``` ### Integration with Slack/Teams ```python #!/usr/bin/env python3 # notify_release_status.py import json import requests import subprocess def send_slack_notification(webhook_url, message): payload = {"text": message} requests.post(webhook_url, json=payload) def get_release_status(): """Get current release status from release planner.""" result = subprocess.run( ["python", "release_planner.py", "--input", "release_plan.json", "--output-format", "json"], capture_output=True, text=True ) return json.loads(result.stdout) # Usage in CI/CD status = get_release_status() if status["assessment"]["overall_status"] == "blocked": message = f"🚫 Release {status['version']} is BLOCKED\n" message += f"Issues: {', '.join(status['assessment']['blocking_issues'])}" send_slack_notification(SLACK_WEBHOOK_URL, message) elif status["assessment"]["overall_status"] == "ready": message = f"✅ Release {status['version']} is READY for deployment!" send_slack_notification(SLACK_WEBHOOK_URL, message) ``` ## Best Practices ### Commit Message Guidelines 1. **Use conventional commits consistently** across your team 2. **Be specific** in commit descriptions: "fix: resolve race condition in user creation" vs "fix: bug" 3. **Reference issues** when applicable: "Closes #123" or "Fixes #456" 4. **Mark breaking changes** clearly with `!` or `BREAKING CHANGE:` footer 5. **Keep first line under 50 characters** when possible ### Release Planning 1. **Plan releases early** with clear feature lists and target dates 2. **Set quality gates** and stick to them (test coverage, security scans, etc.) 3. **Track approvals** from all relevant stakeholders 4. **Document rollback procedures** before deployment 5. **Communicate clearly** with both internal teams and external users ### Version Management 1. **Follow semantic versioning** strictly for predictable releases 2. **Use pre-release versions** for beta testing and gradual rollouts 3. **Tag releases consistently** with proper version numbers 4. **Maintain backwards compatibility** when possible to avoid major version bumps 5. **Document breaking changes** thoroughly with migration guides ## Troubleshooting ### Common Issues **"No valid commits found"** - Ensure git log contains commit messages - Check that commits follow conventional format - Verify input format (git-log vs json) **"Invalid version format"** - Use semantic versioning: 1.2.3, not 1.2 or v1.2.3.beta - Pre-release format: 1.2.3-alpha.1 **"Missing required approvals"** - Check feature risk levels in release plan - High/critical risk features require additional approvals - Update approval status in JSON file ### Debug Mode All scripts support verbose output for debugging: ```bash # Add debug logging python changelog_generator.py --input sample.txt --debug # Validate input data python -c "import json; print(json.load(open('release_plan.json')))" # Test with sample data first python release_planner.py --input assets/sample_release_plan.json ``` ## Contributing When extending these scripts: 1. **Maintain backwards compatibility** for existing command-line interfaces 2. **Add comprehensive tests** for new features 3. **Update documentation** including this README and SKILL.md 4. **Follow Python standards** (PEP 8, type hints where helpful) 5. **Use only standard library** to avoid dependencies ## License This skill is part of the claude-skills repository and follows the same license terms. --- For detailed methodology and background information, see [SKILL.md](SKILL.md). For specific workflow guidance, see the [references](references/) directory. For testing the scripts, use the sample data in the [assets](assets/) directory. ``` ### assets/sample_commits.json ```json [ { "hash": "a1b2c3d", "author": "Sarah Johnson <[email protected]>", "date": "2024-01-15T14:30:22Z", "message": "feat(auth): add OAuth2 integration with Google and GitHub\n\nImplement OAuth2 authentication flow supporting Google and GitHub providers.\nUsers can now sign in using their existing social media accounts, improving\nuser experience and reducing password fatigue.\n\n- Add OAuth2 client configuration\n- Implement authorization code flow\n- Add user profile mapping from providers\n- Include comprehensive error handling\n\nCloses #123\nResolves #145" }, { "hash": "e4f5g6h", "author": "Mike Chen <[email protected]>", "date": "2024-01-15T13:45:18Z", "message": "fix(api): resolve race condition in user creation endpoint\n\nFixed a race condition that occurred when multiple requests attempted\nto create users with the same email address simultaneously. This was\ncausing duplicate user records in some edge cases.\n\n- Added database unique constraint on email field\n- Implemented proper error handling for constraint violations\n- Added retry logic with exponential backoff\n\nFixes #234" }, { "hash": "i7j8k9l", "author": "Emily Davis <[email protected]>", "date": "2024-01-15T12:20:45Z", "message": "docs(readme): update installation and deployment instructions\n\nUpdated README with comprehensive installation guide including:\n- Docker setup instructions\n- Environment variable configuration\n- Database migration steps\n- Troubleshooting common issues" }, { "hash": "m1n2o3p", "author": "David Wilson <[email protected]>", "date": "2024-01-15T11:15:30Z", "message": "feat(ui)!: redesign dashboard with new component library\n\nComplete redesign of the user dashboard using our new component library.\nThis provides better accessibility, improved mobile responsiveness, and\na more modern user interface.\n\nBREAKING CHANGE: The dashboard API endpoints have changed structure.\nFrontend clients must update to use the new /v2/dashboard endpoints.\nThe legacy /v1/dashboard endpoints will be removed in version 3.0.0.\n\n- Implement new Card, Grid, and Chart components\n- Add responsive breakpoints for mobile devices\n- Improve accessibility with proper ARIA labels\n- Add dark mode support\n\nCloses #345, #367, #389" }, { "hash": "q4r5s6t", "author": "Lisa Rodriguez <[email protected]>", "date": "2024-01-15T10:45:12Z", "message": "fix(db): optimize slow query in user search functionality\n\nOptimized the user search query that was causing performance issues\non databases with large user counts. Query time reduced from 2.5s to 150ms.\n\n- Added composite index on (email, username, created_at)\n- Refactored query to use more efficient JOIN structure\n- Added query result caching for common search patterns\n\nFixes #456" }, { "hash": "u7v8w9x", "author": "Tom Anderson <[email protected]>", "date": "2024-01-15T09:30:55Z", "message": "chore(deps): upgrade React to version 18.2.0\n\nUpgrade React and related dependencies to latest stable versions.\nThis includes performance improvements and new concurrent features.\n\n- React: 17.0.2 → 18.2.0\n- React-DOM: 17.0.2 → 18.2.0\n- React-Router: 6.8.0 → 6.8.1\n- Updated all peer dependencies" }, { "hash": "y1z2a3b", "author": "Jennifer Kim <[email protected]>", "date": "2024-01-15T08:15:33Z", "message": "test(auth): add comprehensive tests for OAuth flow\n\nAdded unit and integration tests for the OAuth2 authentication system\nto ensure reliability and prevent regressions.\n\n- Unit tests for OAuth client configuration\n- Integration tests for complete auth flow\n- Mock providers for testing without external dependencies\n- Error scenario testing\n\nTest coverage increased from 72% to 89% for auth module." }, { "hash": "c4d5e6f", "author": "Alex Thompson <[email protected]>", "date": "2024-01-15T07:45:20Z", "message": "perf(image): implement WebP compression reducing size by 40%\n\nReplaced PNG compression with WebP format for uploaded images.\nThis reduces average image file sizes by 40% while maintaining\nvisual quality, improving page load times and reducing bandwidth costs.\n\n- Add WebP encoding support\n- Implement fallback to PNG for older browsers\n- Add quality settings configuration\n- Update image serving endpoints\n\nPerformance improvement: Page load time reduced by 25% on average." }, { "hash": "g7h8i9j", "author": "Rachel Green <[email protected]>", "date": "2024-01-14T16:20:10Z", "message": "feat(payment): add Stripe payment processor integration\n\nIntegrate Stripe as a payment processor to support credit card payments.\nThis enables users to purchase premium features and subscriptions.\n\n- Add Stripe SDK integration\n- Implement payment intent flow\n- Add webhook handling for payment status updates\n- Include comprehensive error handling and logging\n- Add payment method management for users\n\nCloses #567\nCo-authored-by: Payment Team <[email protected]>" }, { "hash": "k1l2m3n", "author": "Chris Martinez <[email protected]>", "date": "2024-01-14T15:30:45Z", "message": "fix(ui): resolve mobile navigation menu overflow issue\n\nFixed navigation menu overflow on mobile devices where long menu items\nwere being cut off and causing horizontal scrolling issues.\n\n- Implement responsive text wrapping\n- Add horizontal scrolling for overflowing content\n- Improve touch targets for better mobile usability\n- Fix z-index conflicts with dropdown menus\n\nFixes #678\nTested on iOS Safari, Chrome Mobile, and Firefox Mobile" }, { "hash": "o4p5q6r", "author": "Anna Kowalski <[email protected]>", "date": "2024-01-14T14:20:15Z", "message": "refactor(api): extract validation logic into reusable middleware\n\nExtracted common validation logic from individual API endpoints into\nreusable middleware functions to reduce code duplication and improve\nmaintainability.\n\n- Create validation middleware for common patterns\n- Refactor user, product, and order endpoints\n- Add comprehensive error messages\n- Improve validation performance by 30%" }, { "hash": "s7t8u9v", "author": "Kevin Park <[email protected]>", "date": "2024-01-14T13:10:30Z", "message": "feat(search): implement fuzzy search with Elasticsearch\n\nImplemented fuzzy search functionality using Elasticsearch to provide\nbetter search results for users with typos or partial matches.\n\n- Integrate Elasticsearch cluster\n- Add fuzzy matching with configurable distance\n- Implement search result ranking algorithm\n- Add search analytics and logging\n\nSearch accuracy improved by 35% in user testing.\nCloses #789" }, { "hash": "w1x2y3z", "author": "Security Team <[email protected]>", "date": "2024-01-14T12:45:22Z", "message": "fix(security): patch SQL injection vulnerability in reports\n\nPatched SQL injection vulnerability in the reports generation endpoint\nthat could allow unauthorized access to sensitive data.\n\n- Implement parameterized queries for all report filters\n- Add input sanitization and validation\n- Update security audit logging\n- Add automated security tests\n\nSeverity: HIGH - CVE-2024-0001\nReported by: External security researcher" } ] ``` ### assets/sample_git_log.txt ```text a1b2c3d feat(auth): add OAuth2 integration with Google and GitHub e4f5g6h fix(api): resolve race condition in user creation endpoint i7j8k9l docs(readme): update installation and deployment instructions m1n2o3p feat(ui)!: redesign dashboard with new component library q4r5s6t fix(db): optimize slow query in user search functionality u7v8w9x chore(deps): upgrade React to version 18.2.0 y1z2a3b test(auth): add comprehensive tests for OAuth flow c4d5e6f perf(image): implement WebP compression reducing size by 40% g7h8i9j feat(payment): add Stripe payment processor integration k1l2m3n fix(ui): resolve mobile navigation menu overflow issue o4p5q6r refactor(api): extract validation logic into reusable middleware s7t8u9v feat(search): implement fuzzy search with Elasticsearch w1x2y3z fix(security): patch SQL injection vulnerability in reports a4b5c6d build(ci): add automated security scanning to deployment pipeline e7f8g9h feat(notification): add email and SMS notification system i1j2k3l fix(payment): handle expired credit cards gracefully m4n5o6p docs(api): generate OpenAPI specification for all endpoints q7r8s9t chore(cleanup): remove deprecated user preference API endpoints u1v2w3x feat(admin)!: redesign admin panel with role-based permissions y4z5a6b fix(db): resolve deadlock issues in concurrent transactions c7d8e9f perf(cache): implement Redis caching for frequent database queries g1h2i3j feat(mobile): add biometric authentication support k4l5m6n fix(api): validate input parameters to prevent XSS attacks o7p8q9r style(ui): update color palette and typography consistency s1t2u3v feat(analytics): integrate Google Analytics 4 tracking w4x5y6z fix(memory): resolve memory leak in image processing service a7b8c9d ci(github): add automated testing for all pull requests e1f2g3h feat(export): add CSV and PDF export functionality for reports i4j5k6l fix(ui): resolve accessibility issues with screen readers m7n8o9p refactor(auth): consolidate authentication logic into single service ``` ### assets/sample_git_log_full.txt ```text commit a1b2c3d4e5f6789012345678901234567890abcd Author: Sarah Johnson <[email protected]> Date: Mon Jan 15 14:30:22 2024 +0000 feat(auth): add OAuth2 integration with Google and GitHub Implement OAuth2 authentication flow supporting Google and GitHub providers. Users can now sign in using their existing social media accounts, improving user experience and reducing password fatigue. - Add OAuth2 client configuration - Implement authorization code flow - Add user profile mapping from providers - Include comprehensive error handling Closes #123 Resolves #145 commit e4f5g6h7i8j9012345678901234567890123abcdef Author: Mike Chen <[email protected]> Date: Mon Jan 15 13:45:18 2024 +0000 fix(api): resolve race condition in user creation endpoint Fixed a race condition that occurred when multiple requests attempted to create users with the same email address simultaneously. This was causing duplicate user records in some edge cases. - Added database unique constraint on email field - Implemented proper error handling for constraint violations - Added retry logic with exponential backoff Fixes #234 commit i7j8k9l0m1n2345678901234567890123456789abcd Author: Emily Davis <[email protected]> Date: Mon Jan 15 12:20:45 2024 +0000 docs(readme): update installation and deployment instructions Updated README with comprehensive installation guide including: - Docker setup instructions - Environment variable configuration - Database migration steps - Troubleshooting common issues commit m1n2o3p4q5r6789012345678901234567890abcdefg Author: David Wilson <[email protected]> Date: Mon Jan 15 11:15:30 2024 +0000 feat(ui)!: redesign dashboard with new component library Complete redesign of the user dashboard using our new component library. This provides better accessibility, improved mobile responsiveness, and a more modern user interface. BREAKING CHANGE: The dashboard API endpoints have changed structure. Frontend clients must update to use the new /v2/dashboard endpoints. The legacy /v1/dashboard endpoints will be removed in version 3.0.0. - Implement new Card, Grid, and Chart components - Add responsive breakpoints for mobile devices - Improve accessibility with proper ARIA labels - Add dark mode support Closes #345, #367, #389 commit q4r5s6t7u8v9012345678901234567890123456abcd Author: Lisa Rodriguez <[email protected]> Date: Mon Jan 15 10:45:12 2024 +0000 fix(db): optimize slow query in user search functionality Optimized the user search query that was causing performance issues on databases with large user counts. Query time reduced from 2.5s to 150ms. - Added composite index on (email, username, created_at) - Refactored query to use more efficient JOIN structure - Added query result caching for common search patterns Fixes #456 commit u7v8w9x0y1z2345678901234567890123456789abcde Author: Tom Anderson <[email protected]> Date: Mon Jan 15 09:30:55 2024 +0000 chore(deps): upgrade React to version 18.2.0 Upgrade React and related dependencies to latest stable versions. This includes performance improvements and new concurrent features. - React: 17.0.2 → 18.2.0 - React-DOM: 17.0.2 → 18.2.0 - React-Router: 6.8.0 → 6.8.1 - Updated all peer dependencies commit y1z2a3b4c5d6789012345678901234567890abcdefg Author: Jennifer Kim <[email protected]> Date: Mon Jan 15 08:15:33 2024 +0000 test(auth): add comprehensive tests for OAuth flow Added unit and integration tests for the OAuth2 authentication system to ensure reliability and prevent regressions. - Unit tests for OAuth client configuration - Integration tests for complete auth flow - Mock providers for testing without external dependencies - Error scenario testing Test coverage increased from 72% to 89% for auth module. commit c4d5e6f7g8h9012345678901234567890123456abcd Author: Alex Thompson <[email protected]> Date: Mon Jan 15 07:45:20 2024 +0000 perf(image): implement WebP compression reducing size by 40% Replaced PNG compression with WebP format for uploaded images. This reduces average image file sizes by 40% while maintaining visual quality, improving page load times and reducing bandwidth costs. - Add WebP encoding support - Implement fallback to PNG for older browsers - Add quality settings configuration - Update image serving endpoints Performance improvement: Page load time reduced by 25% on average. commit g7h8i9j0k1l2345678901234567890123456789abcde Author: Rachel Green <[email protected]> Date: Sun Jan 14 16:20:10 2024 +0000 feat(payment): add Stripe payment processor integration Integrate Stripe as a payment processor to support credit card payments. This enables users to purchase premium features and subscriptions. - Add Stripe SDK integration - Implement payment intent flow - Add webhook handling for payment status updates - Include comprehensive error handling and logging - Add payment method management for users Closes #567 Co-authored-by: Payment Team <[email protected]> commit k1l2m3n4o5p6789012345678901234567890abcdefg Author: Chris Martinez <[email protected]> Date: Sun Jan 14 15:30:45 2024 +0000 fix(ui): resolve mobile navigation menu overflow issue Fixed navigation menu overflow on mobile devices where long menu items were being cut off and causing horizontal scrolling issues. - Implement responsive text wrapping - Add horizontal scrolling for overflowing content - Improve touch targets for better mobile usability - Fix z-index conflicts with dropdown menus Fixes #678 Tested on iOS Safari, Chrome Mobile, and Firefox Mobile ``` ### assets/sample_release_plan.json ```json { "release_name": "Winter 2024 Release", "version": "2.3.0", "target_date": "2024-02-15T10:00:00Z", "features": [ { "id": "AUTH-123", "title": "OAuth2 Integration", "description": "Add support for Google and GitHub OAuth2 authentication", "type": "feature", "assignee": "[email protected]", "status": "ready", "pull_request_url": "https://github.com/ourapp/backend/pull/234", "issue_url": "https://github.com/ourapp/backend/issues/123", "risk_level": "medium", "test_coverage_required": 85.0, "test_coverage_actual": 89.5, "requires_migration": false, "breaking_changes": [], "dependencies": ["AUTH-124"], "qa_approved": true, "security_approved": true, "pm_approved": true }, { "id": "UI-345", "title": "Dashboard Redesign", "description": "Complete redesign of user dashboard with new component library", "type": "breaking_change", "assignee": "[email protected]", "status": "ready", "pull_request_url": "https://github.com/ourapp/frontend/pull/456", "issue_url": "https://github.com/ourapp/frontend/issues/345", "risk_level": "high", "test_coverage_required": 90.0, "test_coverage_actual": 92.3, "requires_migration": true, "migration_complexity": "moderate", "breaking_changes": [ "Dashboard API endpoints changed from /v1/dashboard to /v2/dashboard", "Dashboard widget configuration format updated" ], "dependencies": [], "qa_approved": true, "security_approved": true, "pm_approved": true }, { "id": "PAY-567", "title": "Stripe Payment Integration", "description": "Add Stripe as payment processor for premium features", "type": "feature", "assignee": "[email protected]", "status": "ready", "pull_request_url": "https://github.com/ourapp/backend/pull/678", "issue_url": "https://github.com/ourapp/backend/issues/567", "risk_level": "high", "test_coverage_required": 95.0, "test_coverage_actual": 97.2, "requires_migration": true, "migration_complexity": "complex", "breaking_changes": [], "dependencies": ["SEC-890"], "qa_approved": true, "security_approved": true, "pm_approved": true }, { "id": "SEARCH-789", "title": "Elasticsearch Fuzzy Search", "description": "Implement fuzzy search functionality with Elasticsearch", "type": "feature", "assignee": "[email protected]", "status": "in_progress", "pull_request_url": "https://github.com/ourapp/backend/pull/890", "issue_url": "https://github.com/ourapp/backend/issues/789", "risk_level": "medium", "test_coverage_required": 80.0, "test_coverage_actual": 76.5, "requires_migration": true, "migration_complexity": "moderate", "breaking_changes": [], "dependencies": ["INFRA-234"], "qa_approved": false, "security_approved": true, "pm_approved": true }, { "id": "MOBILE-456", "title": "Biometric Authentication", "description": "Add fingerprint and face ID support for mobile apps", "type": "feature", "assignee": "[email protected]", "status": "blocked", "pull_request_url": null, "issue_url": "https://github.com/ourapp/mobile/issues/456", "risk_level": "medium", "test_coverage_required": 85.0, "test_coverage_actual": null, "requires_migration": false, "breaking_changes": [], "dependencies": ["AUTH-123"], "qa_approved": false, "security_approved": false, "pm_approved": true }, { "id": "PERF-678", "title": "Redis Caching Implementation", "description": "Implement Redis caching for frequently accessed data", "type": "performance", "assignee": "[email protected]", "status": "ready", "pull_request_url": "https://github.com/ourapp/backend/pull/901", "issue_url": "https://github.com/ourapp/backend/issues/678", "risk_level": "low", "test_coverage_required": 75.0, "test_coverage_actual": 82.1, "requires_migration": false, "breaking_changes": [], "dependencies": [], "qa_approved": true, "security_approved": false, "pm_approved": true } ], "quality_gates": [ { "name": "Unit Test Coverage", "required": true, "status": "ready", "details": "Overall test coverage above 85% threshold", "threshold": 85.0, "actual_value": 87.3 }, { "name": "Integration Tests", "required": true, "status": "ready", "details": "All integration tests passing" }, { "name": "Security Scan", "required": true, "status": "pending", "details": "Waiting for security team review of payment integration" }, { "name": "Performance Testing", "required": true, "status": "ready", "details": "Load testing shows 99th percentile response time under 500ms" }, { "name": "Documentation Review", "required": true, "status": "pending", "details": "API documentation needs update for dashboard changes" }, { "name": "Dependency Audit", "required": true, "status": "ready", "details": "No high or critical vulnerabilities found" } ], "stakeholders": [ { "name": "Engineering Team", "role": "developer", "contact": "[email protected]", "notification_type": "slack", "critical_path": true }, { "name": "Product Team", "role": "pm", "contact": "[email protected]", "notification_type": "email", "critical_path": true }, { "name": "QA Team", "role": "qa", "contact": "[email protected]", "notification_type": "slack", "critical_path": true }, { "name": "Security Team", "role": "security", "contact": "[email protected]", "notification_type": "email", "critical_path": false }, { "name": "Customer Support", "role": "support", "contact": "[email protected]", "notification_type": "email", "critical_path": false }, { "name": "Sales Team", "role": "sales", "contact": "[email protected]", "notification_type": "email", "critical_path": false }, { "name": "Beta Users", "role": "customer", "contact": "[email protected]", "notification_type": "email", "critical_path": false } ], "rollback_steps": [ { "order": 1, "description": "Alert incident response team and stakeholders", "estimated_time": "2 minutes", "risk_level": "low", "verification": "Confirm team is aware and responding via Slack" }, { "order": 2, "description": "Switch load balancer to previous version", "command": "kubectl patch service app --patch '{\"spec\": {\"selector\": {\"version\": \"v2.2.1\"}}}'", "estimated_time": "30 seconds", "risk_level": "low", "verification": "Check traffic routing to previous version via monitoring dashboard" }, { "order": 3, "description": "Disable new feature flags", "command": "curl -X POST https://api.example.com/feature-flags/oauth2/disable", "estimated_time": "1 minute", "risk_level": "low", "verification": "Verify feature flags are disabled in admin panel" }, { "order": 4, "description": "Roll back database migrations", "command": "python manage.py migrate app 0042", "estimated_time": "10 minutes", "risk_level": "high", "verification": "Verify database schema and run data integrity checks" }, { "order": 5, "description": "Clear Redis cache", "command": "redis-cli FLUSHALL", "estimated_time": "30 seconds", "risk_level": "medium", "verification": "Confirm cache is cleared and application rebuilds cache properly" }, { "order": 6, "description": "Verify application health", "estimated_time": "5 minutes", "risk_level": "low", "verification": "Check health endpoints, error rates, and core user workflows" }, { "order": 7, "description": "Update status page and notify users", "estimated_time": "5 minutes", "risk_level": "low", "verification": "Confirm status page updated and notifications sent" } ] } ``` ### references/conventional-commits-guide.md ```markdown # Conventional Commits Guide ## Overview Conventional Commits is a specification for adding human and machine readable meaning to commit messages. The specification provides an easy set of rules for creating an explicit commit history, which makes it easier to write automated tools for version management, changelog generation, and release planning. ## Basic Format ``` <type>[optional scope]: <description> [optional body] [optional footer(s)] ``` ## Commit Types ### Primary Types - **feat**: A new feature for the user (correlates with MINOR in semantic versioning) - **fix**: A bug fix for the user (correlates with PATCH in semantic versioning) ### Secondary Types - **build**: Changes that affect the build system or external dependencies (webpack, npm, etc.) - **ci**: Changes to CI configuration files and scripts (Travis, Circle, BrowserStack, SauceLabs) - **docs**: Documentation only changes - **perf**: A code change that improves performance - **refactor**: A code change that neither fixes a bug nor adds a feature - **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc.) - **test**: Adding missing tests or correcting existing tests - **chore**: Other changes that don't modify src or test files - **revert**: Reverts a previous commit ### Breaking Changes Any commit can introduce a breaking change by: 1. Adding `!` after the type: `feat!: remove deprecated API` 2. Including `BREAKING CHANGE:` in the footer ## Scopes Scopes provide additional contextual information about the change. They should be noun describing a section of the codebase: - `auth` - Authentication and authorization - `api` - API changes - `ui` - User interface - `db` - Database related changes - `config` - Configuration changes - `deps` - Dependency updates ## Examples ### Simple Feature ``` feat(auth): add OAuth2 integration Integrate OAuth2 authentication with Google and GitHub providers. Users can now log in using their existing social media accounts. ``` ### Bug Fix ``` fix(api): resolve race condition in user creation When multiple requests tried to create users with the same email simultaneously, duplicate records were sometimes created. Added proper database constraints and error handling. Fixes #234 ``` ### Breaking Change with ! ``` feat(api)!: remove deprecated /v1/users endpoint The deprecated /v1/users endpoint has been removed. All clients should migrate to /v2/users which provides better performance and additional features. BREAKING CHANGE: /v1/users endpoint removed, use /v2/users instead ``` ### Breaking Change with Footer ``` feat(auth): implement new authentication flow Add support for multi-factor authentication and improved session management. This change requires all users to re-authenticate. BREAKING CHANGE: Authentication tokens issued before this release are no longer valid. Users must log in again. ``` ### Performance Improvement ``` perf(image): optimize image compression algorithm Replaced PNG compression with WebP format, reducing image sizes by 40% on average while maintaining visual quality. Closes #456 ``` ### Dependency Update ``` build(deps): upgrade React to version 18.2.0 Updates React and related packages to latest stable versions. Includes performance improvements and new concurrent features. ``` ### Documentation ``` docs(readme): add deployment instructions Added comprehensive deployment guide including Docker setup, environment variables configuration, and troubleshooting tips. ``` ### Revert ``` revert: feat(payment): add cryptocurrency support This reverts commit 667ecc1654a317a13331b17617d973392f415f02. Reverting due to security concerns identified in code review. The feature will be re-implemented with proper security measures. ``` ## Multi-paragraph Body For complex changes, use multiple paragraphs in the body: ``` feat(search): implement advanced search functionality Add support for complex search queries including: - Boolean operators (AND, OR, NOT) - Field-specific searches (title:, author:, date:) - Fuzzy matching with configurable threshold - Search result highlighting The search index has been restructured to support these new features while maintaining backward compatibility with existing simple search queries. Performance testing shows less than 10ms impact on search response times even with complex queries. Closes #789, #823, #901 ``` ## Footers ### Issue References ``` Fixes #123 Closes #234, #345 Resolves #456 ``` ### Breaking Changes ``` BREAKING CHANGE: The `authenticate` function now requires a second parameter for the authentication method. Update all calls from `authenticate(token)` to `authenticate(token, 'bearer')`. ``` ### Co-authors ``` Co-authored-by: Jane Doe <[email protected]> Co-authored-by: John Smith <[email protected]> ``` ### Reviewed By ``` Reviewed-by: Senior Developer <[email protected]> Acked-by: Tech Lead <[email protected]> ``` ## Automation Benefits Using conventional commits enables: ### Automatic Version Bumping - `fix` commits trigger PATCH version bump (1.0.0 → 1.0.1) - `feat` commits trigger MINOR version bump (1.0.0 → 1.1.0) - `BREAKING CHANGE` triggers MAJOR version bump (1.0.0 → 2.0.0) ### Changelog Generation ```markdown ## [1.2.0] - 2024-01-15 ### Added - OAuth2 integration (auth) - Advanced search functionality (search) ### Fixed - Race condition in user creation (api) - Memory leak in image processing (image) ### Breaking Changes - Authentication tokens issued before this release are no longer valid ``` ### Release Notes Generate user-friendly release notes automatically from commit history, filtering out internal changes and highlighting user-facing improvements. ## Best Practices ### Writing Good Descriptions - Use imperative mood: "add feature" not "added feature" - Start with lowercase letter - No period at the end - Limit to 50 characters when possible - Be specific and descriptive ### Good Examples ``` feat(auth): add password reset functionality fix(ui): resolve mobile navigation menu overflow perf(db): optimize user query with proper indexing ``` ### Bad Examples ``` feat: stuff fix: bug update: changes ``` ### Body Guidelines - Separate subject from body with blank line - Wrap body at 72 characters - Use body to explain what and why, not how - Reference issues and PRs when relevant ### Scope Guidelines - Use consistent scope naming across the team - Keep scopes short and meaningful - Document your team's scope conventions - Consider using scopes that match your codebase structure ## Tools and Integration ### Git Hooks Use tools like `commitizen` or `husky` to enforce conventional commit format: ```bash # Install commitizen npm install -g commitizen cz-conventional-changelog # Configure echo '{ "path": "cz-conventional-changelog" }' > ~/.czrc # Use git cz ``` ### Automated Validation Add commit message validation to prevent non-conventional commits: ```javascript // commitlint.config.js module.exports = { extends: ['@commitlint/config-conventional'], rules: { 'type-enum': [ 2, 'always', ['feat', 'fix', 'docs', 'style', 'refactor', 'perf', 'test', 'build', 'ci', 'chore', 'revert'] ], 'subject-case': [2, 'always', 'lower-case'], 'subject-max-length': [2, 'always', 50] } }; ``` ### CI/CD Integration Integrate with release automation tools: - **semantic-release**: Automated version management and package publishing - **standard-version**: Generate changelog and tag releases - **release-please**: Google's release automation tool ## Common Mistakes ### Mixing Multiple Changes ``` # Bad: Multiple unrelated changes feat: add login page and fix CSS bug and update dependencies # Good: Separate commits feat(auth): add login page fix(ui): resolve CSS styling issue build(deps): update React to version 18 ``` ### Vague Descriptions ``` # Bad: Not descriptive fix: bug in code feat: new stuff # Good: Specific and clear fix(api): resolve null pointer exception in user validation feat(search): implement fuzzy matching algorithm ``` ### Missing Breaking Change Indicators ``` # Bad: Breaking change not marked feat(api): update user authentication # Good: Properly marked breaking change feat(api)!: update user authentication BREAKING CHANGE: All API clients must now include authentication headers in every request. Anonymous access is no longer supported. ``` ## Team Guidelines ### Establishing Conventions 1. **Define scope vocabulary**: Create a list of approved scopes for your project 2. **Document examples**: Provide team-specific examples of good commits 3. **Set up tooling**: Use linters and hooks to enforce standards 4. **Review process**: Include commit message quality in code reviews 5. **Training**: Ensure all team members understand the format ### Scope Examples by Project Type **Web Application:** - `auth`, `ui`, `api`, `db`, `config`, `deploy` **Library/SDK:** - `core`, `utils`, `docs`, `examples`, `tests` **Mobile App:** - `ios`, `android`, `shared`, `ui`, `network`, `storage` By following conventional commits consistently, your team will have a clear, searchable commit history that enables powerful automation and improves the overall development workflow. ``` ### references/hotfix-procedures.md ```markdown # Hotfix Procedures ## Overview Hotfixes are emergency releases designed to address critical production issues that cannot wait for the regular release cycle. This document outlines classification, procedures, and best practices for managing hotfixes across different development workflows. ## Severity Classification ### P0 - Critical (Production Down) **Definition:** Complete system outage, data corruption, or security breach affecting all users. **Examples:** - Server crashes preventing any user access - Database corruption causing data loss - Security vulnerability being actively exploited - Payment system completely non-functional - Authentication system failure preventing all logins **Response Requirements:** - **Timeline:** Fix deployed within 2 hours - **Approval:** Engineering Lead + On-call Manager (verbal approval acceptable) - **Process:** Emergency deployment bypassing normal gates - **Communication:** Immediate notification to all stakeholders - **Documentation:** Post-incident review required within 24 hours **Escalation:** - Page on-call engineer immediately - Escalate to Engineering Lead within 15 minutes - Notify CEO/CTO if resolution exceeds 4 hours ### P1 - High (Major Feature Broken) **Definition:** Critical functionality broken affecting significant portion of users. **Examples:** - Core user workflow completely broken - Payment processing failures affecting >50% of transactions - Search functionality returning no results - Mobile app crashes on startup - API returning 500 errors for main endpoints **Response Requirements:** - **Timeline:** Fix deployed within 24 hours - **Approval:** Engineering Lead + Product Manager - **Process:** Expedited review and testing - **Communication:** Stakeholder notification within 1 hour - **Documentation:** Root cause analysis within 48 hours **Escalation:** - Notify on-call engineer within 30 minutes - Escalate to Engineering Lead within 2 hours - Daily updates to Product/Business stakeholders ### P2 - Medium (Minor Feature Issues) **Definition:** Non-critical functionality issues with limited user impact. **Examples:** - Cosmetic UI issues affecting user experience - Non-essential features not working properly - Performance degradation not affecting core workflows - Minor API inconsistencies - Reporting/analytics data inaccuracies **Response Requirements:** - **Timeline:** Include in next regular release - **Approval:** Standard pull request review process - **Process:** Normal development and testing cycle - **Communication:** Include in regular release notes - **Documentation:** Standard issue tracking **Escalation:** - Create ticket in normal backlog - No special escalation required - Include in release planning discussions ## Hotfix Workflows by Development Model ### Git Flow Hotfix Process #### Branch Structure ``` main (v1.2.3) ← hotfix/security-patch → main (v1.2.4) → develop ``` #### Step-by-Step Process 1. **Create Hotfix Branch** ```bash git checkout main git pull origin main git checkout -b hotfix/security-patch ``` 2. **Implement Fix** - Make minimal changes addressing only the specific issue - Include tests to prevent regression - Update version number (patch increment) ```bash # Fix the issue git add . git commit -m "fix: resolve SQL injection vulnerability" # Version bump echo "1.2.4" > VERSION git add VERSION git commit -m "chore: bump version to 1.2.4" ``` 3. **Test Fix** - Run automated test suite - Manual testing of affected functionality - Security review if applicable ```bash # Run tests npm test python -m pytest # Security scan npm audit bandit -r src/ ``` 4. **Deploy to Staging** ```bash # Deploy hotfix branch to staging git push origin hotfix/security-patch # Trigger staging deployment via CI/CD ``` 5. **Merge to Production** ```bash # Merge to main git checkout main git merge --no-ff hotfix/security-patch git tag -a v1.2.4 -m "Hotfix: Security vulnerability patch" git push origin main --tags # Merge back to develop git checkout develop git merge --no-ff hotfix/security-patch git push origin develop # Clean up git branch -d hotfix/security-patch git push origin --delete hotfix/security-patch ``` ### GitHub Flow Hotfix Process #### Branch Structure ``` main ← hotfix/critical-fix → main (immediate deploy) ``` #### Step-by-Step Process 1. **Create Fix Branch** ```bash git checkout main git pull origin main git checkout -b hotfix/payment-gateway-fix ``` 2. **Implement and Test** ```bash # Make the fix git add . git commit -m "fix(payment): resolve gateway timeout issue" git push origin hotfix/payment-gateway-fix ``` 3. **Create Emergency PR** ```bash # Use GitHub CLI or web interface gh pr create --title "HOTFIX: Payment gateway timeout" \ --body "Critical fix for payment processing failures" \ --reviewer engineering-team \ --label hotfix ``` 4. **Deploy Branch for Testing** ```bash # Deploy branch to staging for validation ./deploy.sh hotfix/payment-gateway-fix staging # Quick smoke tests ``` 5. **Emergency Merge and Deploy** ```bash # After approval, merge and deploy gh pr merge --squash # Automatic deployment to production via CI/CD ``` ### Trunk-based Hotfix Process #### Direct Commit Approach ```bash # For small fixes, commit directly to main git checkout main git pull origin main # Make fix git add . git commit -m "fix: resolve memory leak in user session handling" git push origin main # Automatic deployment triggers ``` #### Feature Flag Rollback ```bash # For feature-related issues, disable via feature flag curl -X POST api/feature-flags/new-search/disable # Verify issue resolved # Plan proper fix for next deployment ``` ## Emergency Response Procedures ### Incident Declaration Process 1. **Detection and Assessment** (0-5 minutes) - Monitor alerts or user reports identify issue - Assess severity using classification matrix - Determine if hotfix is required 2. **Team Assembly** (5-10 minutes) - Page appropriate on-call engineer - Assemble incident response team - Establish communication channel (Slack, Teams) 3. **Initial Response** (10-30 minutes) - Create incident ticket/document - Begin investigating root cause - Implement immediate mitigations if possible 4. **Hotfix Development** (30 minutes - 2 hours) - Create hotfix branch - Implement minimal fix - Test fix in isolation 5. **Deployment** (15-30 minutes) - Deploy to staging for validation - Deploy to production - Monitor for successful resolution 6. **Verification** (15-30 minutes) - Confirm issue is resolved - Monitor system stability - Update stakeholders ### Communication Templates #### P0 Initial Alert ``` 🚨 CRITICAL INCIDENT - Production Down Status: Investigating Impact: Complete service outage Affected Users: All users Started: 2024-01-15 14:30 UTC Incident Commander: @john.doe Current Actions: - Investigating root cause - Preparing emergency fix - Will update every 15 minutes Status Page: https://status.ourapp.com Incident Channel: #incident-2024-001 ``` #### P0 Resolution Notice ``` ✅ RESOLVED - Production Restored Status: Resolved Resolution Time: 1h 23m Root Cause: Database connection pool exhaustion Fix: Increased connection limits and restarted services Timeline: 14:30 UTC - Issue detected 14:45 UTC - Root cause identified 15:20 UTC - Fix deployed 15:35 UTC - Full functionality restored Post-incident review scheduled for tomorrow 10:00 AM. Thank you for your patience. ``` #### P1 Status Update ``` ⚠️ Issue Update - Payment Processing Status: Fix deployed, monitoring Impact: Payment failures reduced from 45% to <2% ETA: Complete resolution within 2 hours Actions taken: - Deployed hotfix to address timeout issues - Increased monitoring on payment gateway - Contacting affected customers Next update in 30 minutes or when resolved. ``` ### Rollback Procedures #### When to Rollback - Fix doesn't resolve the issue - Fix introduces new problems - System stability is compromised - Data corruption is detected #### Rollback Process 1. **Immediate Assessment** (2-5 minutes) ```bash # Check system health curl -f https://api.ourapp.com/health # Review error logs kubectl logs deployment/app --tail=100 # Check key metrics ``` 2. **Rollback Execution** (5-15 minutes) ```bash # Git-based rollback git checkout main git revert HEAD git push origin main # Or container-based rollback kubectl rollout undo deployment/app # Or load balancer switch aws elbv2 modify-target-group --target-group-arn arn:aws:elasticloadbalancing:us-east-1:123456789012:targetgroup/previous-version ``` 3. **Verification** (5-10 minutes) ```bash # Confirm rollback successful # Check system health endpoints # Verify core functionality working # Monitor error rates and performance ``` 4. **Communication** ``` 🔄 ROLLBACK COMPLETE The hotfix has been rolled back due to [reason]. System is now stable on previous version. We are investigating the issue and will provide updates. ``` ## Testing Strategies for Hotfixes ### Pre-deployment Testing #### Automated Testing ```bash # Run full test suite npm test pytest tests/ go test ./... # Security scanning npm audit --audit-level high bandit -r src/ gosec ./... # Integration tests ./run_integration_tests.sh # Load testing (if performance-related) artillery quick --count 100 --num 10 https://staging.ourapp.com ``` #### Manual Testing Checklist - [ ] Core user workflow functions correctly - [ ] Authentication and authorization working - [ ] Payment processing (if applicable) - [ ] Data integrity maintained - [ ] No new error logs or exceptions - [ ] Performance within acceptable range - [ ] Mobile app functionality (if applicable) - [ ] Third-party integrations working #### Staging Validation ```bash # Deploy to staging ./deploy.sh hotfix/critical-fix staging # Run smoke tests curl -f https://staging.ourapp.com/api/health ./smoke_tests.sh # Manual verification of specific issue # Document test results ``` ### Post-deployment Monitoring #### Immediate Monitoring (First 30 minutes) - Error rate and count - Response time and latency - CPU and memory usage - Database connection counts - Key business metrics #### Extended Monitoring (First 24 hours) - User activity patterns - Feature usage statistics - Customer support tickets - Performance trends - Security log analysis #### Monitoring Scripts ```bash #!/bin/bash # monitor_hotfix.sh - Post-deployment monitoring echo "=== Hotfix Deployment Monitoring ===" echo "Deployment time: $(date)" echo # Check application health echo "--- Application Health ---" curl -s https://api.ourapp.com/health | jq '.' # Check error rates echo "--- Error Rates (last 30min) ---" curl -s "https://api.datadog.com/api/v1/query?query=sum:application.errors{*}" \ -H "DD-API-KEY: $DATADOG_API_KEY" | jq '.series[0].pointlist[-1][1]' # Check response times echo "--- Response Times ---" curl -s "https://api.datadog.com/api/v1/query?query=avg:application.response_time{*}" \ -H "DD-API-KEY: $DATADOG_API_KEY" | jq '.series[0].pointlist[-1][1]' # Check database connections echo "--- Database Status ---" psql -h db.ourapp.com -U readonly -c "SELECT count(*) as active_connections FROM pg_stat_activity;" echo "=== Monitoring Complete ===" ``` ## Documentation and Learning ### Incident Documentation Template ```markdown # Incident Report: [Brief Description] ## Summary - **Incident ID:** INC-2024-001 - **Severity:** P0/P1/P2 - **Start Time:** 2024-01-15 14:30 UTC - **End Time:** 2024-01-15 15:45 UTC - **Duration:** 1h 15m - **Impact:** [Description of user/business impact] ## Root Cause [Detailed explanation of what went wrong and why] ## Timeline | Time | Event | |------|-------| | 14:30 | Issue detected via monitoring alert | | 14:35 | Incident team assembled | | 14:45 | Root cause identified | | 15:00 | Fix developed and tested | | 15:20 | Fix deployed to production | | 15:45 | Issue confirmed resolved | ## Resolution [What was done to fix the issue] ## Lessons Learned ### What went well - Quick detection through monitoring - Effective team coordination - Minimal user impact ### What could be improved - Earlier detection possible with better alerting - Testing could have caught this issue - Communication could be more proactive ## Action Items - [ ] Improve monitoring for [specific area] - [ ] Add automated test for [specific scenario] - [ ] Update documentation for [specific process] - [ ] Training on [specific topic] for team ## Prevention Measures [How we'll prevent this from happening again] ``` ### Post-Incident Review Process 1. **Schedule Review** (within 24-48 hours) - Involve all key participants - Book 60-90 minute session - Prepare incident timeline 2. **Blameless Analysis** - Focus on systems and processes, not individuals - Understand contributing factors - Identify improvement opportunities 3. **Action Plan** - Concrete, assignable tasks - Realistic timelines - Clear success criteria 4. **Follow-up** - Track action item completion - Share learnings with broader team - Update procedures based on insights ### Knowledge Sharing #### Runbook Updates After each hotfix, update relevant runbooks: - Add new troubleshooting steps - Update contact information - Refine escalation procedures - Document new tools or processes #### Team Training - Share incident learnings in team meetings - Conduct tabletop exercises for common scenarios - Update onboarding materials with hotfix procedures - Create decision trees for severity classification #### Automation Improvements - Add alerts for new failure modes - Automate manual steps where possible - Improve deployment and rollback processes - Enhance monitoring and observability ## Common Pitfalls and Best Practices ### Common Pitfalls ❌ **Over-engineering the fix** - Making broad changes instead of minimal targeted fix - Adding features while fixing bugs - Refactoring unrelated code ❌ **Insufficient testing** - Skipping automated tests due to time pressure - Not testing the exact scenario that caused the issue - Deploying without staging validation ❌ **Poor communication** - Not notifying stakeholders promptly - Unclear or infrequent status updates - Forgetting to announce resolution ❌ **Inadequate monitoring** - Not watching system health after deployment - Missing secondary effects of the fix - Failing to verify the issue is actually resolved ### Best Practices ✅ **Keep fixes minimal and focused** - Address only the specific issue - Avoid scope creep or improvements - Save refactoring for regular releases ✅ **Maintain clear communication** - Set up dedicated incident channel - Provide regular status updates - Use clear, non-technical language for business stakeholders ✅ **Test thoroughly but efficiently** - Focus testing on affected functionality - Use automated tests where possible - Validate in staging before production ✅ **Document everything** - Maintain timeline of events - Record decisions and rationale - Share lessons learned with team ✅ **Plan for rollback** - Always have a rollback plan ready - Test rollback procedure in advance - Monitor closely after deployment By following these procedures and continuously improving based on experience, teams can handle production emergencies effectively while minimizing impact and learning from each incident. ``` ### references/release-workflow-comparison.md ```markdown # Release Workflow Comparison ## Overview This document compares the three most popular branching and release workflows: Git Flow, GitHub Flow, and Trunk-based Development. Each approach has distinct advantages and trade-offs depending on your team size, deployment frequency, and risk tolerance. ## Git Flow ### Structure ``` main (production) ↑ release/1.2.0 ← develop (integration) ← feature/user-auth ↑ ← feature/payment-api hotfix/critical-fix ``` ### Branch Types - **main**: Production-ready code, tagged releases - **develop**: Integration branch for next release - **feature/***: Individual features, merged to develop - **release/X.Y.Z**: Release preparation, branched from develop - **hotfix/***: Critical fixes, branched from main ### Typical Flow 1. Create feature branch from develop: `git checkout -b feature/login develop` 2. Work on feature, commit changes 3. Merge feature to develop when complete 4. When ready for release, create release branch: `git checkout -b release/1.2.0 develop` 5. Finalize release (version bump, changelog, bug fixes) 6. Merge release branch to both main and develop 7. Tag release: `git tag v1.2.0` 8. Deploy from main branch ### Advantages - **Clear separation** between production and development code - **Stable main branch** always represents production state - **Parallel development** of features without interference - **Structured release process** with dedicated release branches - **Hotfix support** without disrupting development work - **Good for scheduled releases** and traditional release cycles ### Disadvantages - **Complex workflow** with many branch types - **Merge overhead** from multiple integration points - **Delayed feedback** from long-lived feature branches - **Integration conflicts** when merging large features - **Slower deployment** due to process overhead - **Not ideal for continuous deployment** ### Best For - Large teams (10+ developers) - Products with scheduled release cycles - Enterprise software with formal testing phases - Projects requiring stable release branches - Teams comfortable with complex Git workflows ### Example Commands ```bash # Start new feature git checkout develop git checkout -b feature/user-authentication # Finish feature git checkout develop git merge --no-ff feature/user-authentication git branch -d feature/user-authentication # Start release git checkout develop git checkout -b release/1.2.0 # Version bump and changelog updates git commit -am "Bump version to 1.2.0" # Finish release git checkout main git merge --no-ff release/1.2.0 git tag -a v1.2.0 -m "Release version 1.2.0" git checkout develop git merge --no-ff release/1.2.0 git branch -d release/1.2.0 # Hotfix git checkout main git checkout -b hotfix/security-patch # Fix the issue git commit -am "Fix security vulnerability" git checkout main git merge --no-ff hotfix/security-patch git tag -a v1.2.1 -m "Hotfix version 1.2.1" git checkout develop git merge --no-ff hotfix/security-patch ``` ## GitHub Flow ### Structure ``` main ← feature/user-auth ← feature/payment-api ← hotfix/critical-fix ``` ### Branch Types - **main**: Production-ready code, deployed automatically - **feature/***: All changes, regardless of size or type ### Typical Flow 1. Create feature branch from main: `git checkout -b feature/login main` 2. Work on feature with regular commits and pushes 3. Open pull request when ready for feedback 4. Deploy feature branch to staging for testing 5. Merge to main when approved and tested 6. Deploy main to production automatically 7. Delete feature branch ### Advantages - **Simple workflow** with only two branch types - **Fast deployment** with minimal process overhead - **Continuous integration** with frequent merges to main - **Early feedback** through pull request reviews - **Deploy from branches** allows testing before merge - **Good for continuous deployment** ### Disadvantages - **Main can be unstable** if testing is insufficient - **No release branches** for coordinating multiple features - **Limited hotfix process** requires careful coordination - **Requires strong testing** and CI/CD infrastructure - **Not suitable for scheduled releases** - **Can be chaotic** with many simultaneous features ### Best For - Small to medium teams (2-10 developers) - Web applications with continuous deployment - Products with rapid iteration cycles - Teams with strong testing and CI/CD practices - Projects where main is always deployable ### Example Commands ```bash # Start new feature git checkout main git pull origin main git checkout -b feature/user-authentication # Regular work git add . git commit -m "feat(auth): add login form validation" git push origin feature/user-authentication # Deploy branch for testing # (Usually done through CI/CD) ./deploy.sh feature/user-authentication staging # Merge when ready git checkout main git merge feature/user-authentication git push origin main git branch -d feature/user-authentication # Automatic deployment to production # (Triggered by push to main) ``` ## Trunk-based Development ### Structure ``` main ← short-feature-branch (1-3 days max) ← another-short-branch ← direct-commits ``` ### Branch Types - **main**: The single source of truth, always deployable - **Short-lived branches**: Optional, for changes taking >1 day ### Typical Flow 1. Commit directly to main for small changes 2. Create short-lived branch for larger changes (max 2-3 days) 3. Merge to main frequently (multiple times per day) 4. Use feature flags to hide incomplete features 5. Deploy main to production multiple times per day 6. Release by enabling feature flags, not code deployment ### Advantages - **Simplest workflow** with minimal branching - **Fastest integration** with continuous merges - **Reduced merge conflicts** from short-lived branches - **Always deployable main** through feature flags - **Fastest feedback loop** with immediate integration - **Excellent for CI/CD** and DevOps practices ### Disadvantages - **Requires discipline** to keep main stable - **Needs feature flags** for incomplete features - **Limited code review** for direct commits - **Can be destabilizing** without proper testing - **Requires advanced CI/CD** infrastructure - **Not suitable for teams** uncomfortable with frequent changes ### Best For - Expert teams with strong DevOps culture - Products requiring very fast iteration - Microservices architectures - Teams practicing continuous deployment - Organizations with mature testing practices ### Example Commands ```bash # Small change - direct to main git checkout main git pull origin main # Make changes git add . git commit -m "fix(ui): resolve button alignment issue" git push origin main # Larger change - short branch git checkout main git pull origin main git checkout -b payment-integration # Work for 1-2 days maximum git add . git commit -m "feat(payment): add Stripe integration" git push origin payment-integration # Immediate merge git checkout main git merge payment-integration git push origin main git branch -d payment-integration # Feature flag usage if (featureFlags.enabled('stripe_payments', userId)) { return renderStripePayment(); } else { return renderLegacyPayment(); } ``` ## Feature Comparison Matrix | Aspect | Git Flow | GitHub Flow | Trunk-based | |--------|----------|-------------|-------------| | **Complexity** | High | Medium | Low | | **Learning Curve** | Steep | Moderate | Gentle | | **Deployment Frequency** | Weekly/Monthly | Daily | Multiple/day | | **Branch Lifetime** | Weeks/Months | Days/Weeks | Hours/Days | | **Main Stability** | Very High | High | High* | | **Release Coordination** | Excellent | Limited | Feature Flags | | **Hotfix Support** | Built-in | Manual | Direct | | **Merge Conflicts** | High | Medium | Low | | **Team Size** | 10+ | 3-10 | Any | | **CI/CD Requirements** | Medium | High | Very High | *With proper feature flags and testing ## Release Strategies by Workflow ### Git Flow Releases ```bash # Scheduled release every 2 weeks git checkout develop git checkout -b release/2.3.0 # Version management echo "2.3.0" > VERSION npm version 2.3.0 --no-git-tag-version python setup.py --version 2.3.0 # Changelog generation git log --oneline release/2.2.0..HEAD --pretty=format:"%s" > CHANGELOG_DRAFT.md # Testing and bug fixes in release branch git commit -am "fix: resolve issue found in release testing" # Finalize release git checkout main git merge --no-ff release/2.3.0 git tag -a v2.3.0 -m "Release 2.3.0" # Deploy tagged version docker build -t app:2.3.0 . kubectl set image deployment/app app=app:2.3.0 ``` ### GitHub Flow Releases ```bash # Deploy every merge to main git checkout main git merge feature/new-payment-method # Automatic deployment via CI/CD # .github/workflows/deploy.yml triggers on push to main # Tag releases for tracking (optional) git tag -a v2.3.$(date +%Y%m%d%H%M) -m "Production deployment" # Rollback if needed git revert HEAD git push origin main # Triggers automatic rollback deployment ``` ### Trunk-based Releases ```bash # Continuous deployment with feature flags git checkout main git add feature_flags.json git commit -m "feat: enable new payment method for 10% of users" git push origin main # Gradual rollout curl -X POST api/feature-flags/payment-v2/rollout/25 # 25% of users # Monitor metrics... curl -X POST api/feature-flags/payment-v2/rollout/50 # 50% of users # Monitor metrics... curl -X POST api/feature-flags/payment-v2/rollout/100 # Full rollout # Remove flag after successful rollout git rm old_payment_code.js git commit -m "cleanup: remove legacy payment code" ``` ## Choosing the Right Workflow ### Decision Matrix **Choose Git Flow if:** - ✅ Team size > 10 developers - ✅ Scheduled release cycles (weekly/monthly) - ✅ Multiple versions supported simultaneously - ✅ Formal testing and QA processes - ✅ Complex enterprise software - ❌ Need rapid deployment - ❌ Small team or startup **Choose GitHub Flow if:** - ✅ Team size 3-10 developers - ✅ Web applications or APIs - ✅ Strong CI/CD and testing - ✅ Daily or continuous deployment - ✅ Simple release requirements - ❌ Complex release coordination needed - ❌ Multiple release branches required **Choose Trunk-based Development if:** - ✅ Expert development team - ✅ Mature DevOps practices - ✅ Microservices architecture - ✅ Feature flag infrastructure - ✅ Multiple deployments per day - ✅ Strong automated testing - ❌ Junior developers - ❌ Complex integration requirements ### Migration Strategies #### From Git Flow to GitHub Flow 1. **Simplify branching**: Eliminate develop branch, work directly with main 2. **Increase deployment frequency**: Move from scheduled to continuous releases 3. **Strengthen testing**: Improve automated test coverage and CI/CD 4. **Reduce branch lifetime**: Limit feature branches to 1-2 weeks maximum 5. **Train team**: Educate on simpler workflow and increased responsibility #### From GitHub Flow to Trunk-based 1. **Implement feature flags**: Add feature toggle infrastructure 2. **Improve CI/CD**: Ensure all tests run in <10 minutes 3. **Increase commit frequency**: Encourage multiple commits per day 4. **Reduce branch usage**: Start committing small changes directly to main 5. **Monitor stability**: Ensure main remains deployable at all times #### From Trunk-based to Git Flow 1. **Add structure**: Introduce develop and release branches 2. **Reduce deployment frequency**: Move to scheduled release cycles 3. **Extend branch lifetime**: Allow longer feature development cycles 4. **Formalize process**: Add approval gates and testing phases 5. **Coordinate releases**: Plan features for specific release versions ## Anti-patterns to Avoid ### Git Flow Anti-patterns - **Long-lived feature branches** (>2 weeks) - **Skipping release branches** for small releases - **Direct commits to main** bypassing develop - **Forgetting to merge back** to develop after hotfixes - **Complex merge conflicts** from delayed integration ### GitHub Flow Anti-patterns - **Unstable main branch** due to insufficient testing - **Long-lived feature branches** defeating the purpose - **Skipping pull request reviews** for speed - **Direct production deployment** without staging validation - **No rollback plan** when deployments fail ### Trunk-based Anti-patterns - **Committing broken code** to main branch - **Feature branches lasting weeks** defeating the philosophy - **No feature flags** for incomplete features - **Insufficient automated testing** leading to instability - **Poor CI/CD pipeline** causing deployment delays ## Conclusion The choice of release workflow significantly impacts your team's productivity, code quality, and deployment reliability. Consider your team size, technical maturity, deployment requirements, and organizational culture when making this decision. **Start conservative** (Git Flow) and evolve toward more agile approaches (GitHub Flow, Trunk-based) as your team's skills and infrastructure mature. The key is consistency within your team and alignment with your organization's goals and constraints. Remember: **The best workflow is the one your team can execute consistently and reliably**. ```