Skip to content

BRANCHING_STRATEGY.md

Latest commit

 

History

History
742 lines (553 loc) · 16 KB

BRANCHING_STRATEGY.md

File metadata and controls

742 lines (553 loc) · 16 KB

Branching Strategy

ClaudeForge uses a Standard Branching Strategy with protected branches and automated quality gates.

Overview

feature/*, fix/*, hotfix/* → dev → main
         ↓                    ↓      ↓
    Development          Testing  Production

Three permanent branches:

  • main - Production-ready code, always deployable
  • dev - Integration branch for features
  • (temporary) - Feature, fix, and hotfix branches

Branch protection:

  • ✅ No direct commits to main or dev
  • ✅ All changes via pull requests
  • ✅ Automated quality gates required
  • ✅ Conventional Commits enforced
  • ✅ Linear history (squash merges)

Branch Types

Main Branch

Purpose: Production-ready releases only

Protection Rules:

  • ✅ Require pull request before merging
  • ✅ Require status checks to pass: quality-gates, production-build
  • ✅ Require linear history (squash merges only)
  • ✅ No force pushes
  • ✅ No deletions
  • ✅ Require review from CODEOWNERS

Who can merge:

  • Only dev, release/*, or dependabot/* branches
  • After passing dev-to-main.yml workflow

Triggers:

  • dev-to-main.yml workflow on PR
  • release.yml workflow for GitHub releases

Typical state:

  • Always matches latest GitHub release
  • Only updated when releasing new version
  • Every commit corresponds to a version tag (v1.0.0, v1.1.0, etc.)

Dev Branch

Purpose: Integration branch for all features

Protection Rules:

  • ✅ Require pull request before merging
  • ✅ Require status checks to pass: quality-gates, validate-pr
  • ✅ Require linear history (squash merges only)
  • ✅ No force pushes
  • ✅ No deletions

Who can merge:

  • Feature branches (feature/*)
  • Fix branches (fix/*)
  • Hotfix branches (hotfix/*)
  • Test branches (test/*)
  • Refactor branches (refactor/*)
  • Docs branches (docs/*)

Triggers:

  • pr-into-dev.yml workflow on PR

Typical state:

  • Contains completed features awaiting release
  • Ahead of main by several commits
  • Reset to main only after release (via merge)

Feature Branches

Naming Convention: feature/<description>

Purpose: New features or enhancements

Examples:

  • feature/add-rust-templates
  • feature/vscode-extension
  • feature/ai-suggestions

Lifecycle:

  1. Create from latest dev: git checkout dev && git pull && git checkout -b feature/my-feature
  2. Make changes, commit with Conventional Commits
  3. Push to origin: git push -u origin feature/my-feature
  4. Create PR to dev
  5. Pass quality gates and code review
  6. Squash merge to dev
  7. Delete feature branch

PR Requirements:

  • ✅ Title must follow Conventional Commits: feat(scope): description
  • ✅ At least one linked issue (recommended)
  • ✅ All quality gates pass
  • ✅ Code review approved (if CODEOWNERS configured)

Fix Branches

Naming Convention: fix/<description>

Purpose: Bug fixes

Examples:

  • fix/installer-windows-path
  • fix/python-syntax-validation
  • fix/broken-markdown-links

Lifecycle: Same as feature branches, but:

  • PR title prefix: fix(scope): description
  • Link to bug issue with Fixes #123 or Closes #123

PR Requirements:

  • ✅ Title: fix(scope): description
  • ✅ Linked to bug issue
  • ✅ Quality gates pass
  • ✅ Test fix if applicable

Hotfix Branches

Naming Convention: hotfix/<description>

Purpose: Urgent fixes for production issues

Examples:

  • hotfix/critical-installer-bug
  • hotfix/security-patch

Lifecycle:

  1. Create from dev: git checkout dev && git pull && git checkout -b hotfix/issue-name
  2. Make minimal fix
  3. Create PR to dev
  4. After merge to dev, immediately create PR dev → main
  5. Fast-track review and merge

PR Requirements:

  • ✅ Title: fix(scope): description or hotfix(scope): description
  • ✅ Link to critical issue
  • ✅ Quality gates pass (can be expedited)
  • ✅ Fast-track review

Special considerations:

  • Prioritize speed over perfection
  • Minimal changes only
  • Document reason for hotfix in PR description

Test Branches

Naming Convention: test/<description>

Purpose: Testing experiments or validations

Examples:

  • test/new-quality-gate
  • test/workflow-validation

Lifecycle:

  • Same as feature branches
  • PR title: test(scope): description
  • May not require linked issue

Refactor Branches

Naming Convention: refactor/<description>

Purpose: Code improvements without changing functionality

Examples:

  • refactor/simplify-analyzer
  • refactor/improve-error-handling

Lifecycle:

  • Same as feature branches
  • PR title: refactor(scope): description
  • Should not change external behavior

Docs Branches

Naming Convention: docs/<description>

Purpose: Documentation-only changes

Examples:

  • docs/update-installation-guide
  • docs/add-troubleshooting-section

Lifecycle:

  • Same as feature branches
  • PR title: docs: description or docs(scope): description
  • Can skip some quality gates (Python, Bash)

Workflow Diagrams

Standard Feature Flow

Developer's machine:
git checkout dev
git pull origin dev
git checkout -b feature/add-templates
# Make changes
git add .
git commit -m "feat(skill): add Rust template support"
git push -u origin feature/add-templates

GitHub:
Create PR: feature/add-templates → dev
↓
pr-into-dev.yml runs:
├─ Branch name validation ✅
├─ PR title validation ✅
├─ Linked issue check ⚠️
├─ Quality gates ✅
└─ Ready for review

Code review + approval
↓
Squash and merge to dev
↓
Delete feature branch

Release Flow

Dev branch ready for release:
├─ All features merged
├─ CHANGELOG.md updated
└─ Version bumped

GitHub:
Create PR: dev → main
↓
dev-to-main.yml runs:
├─ Source branch validation ✅ (dev allowed)
├─ CHANGELOG.md check ✅
├─ Version consistency ✅
├─ Quality gates ✅
├─ Production build validation ✅
└─ Ready for production

Approval + merge to main
↓
Run release.yml workflow:
├─ Input version: 1.1.0
├─ Validate version format ✅
├─ Extract CHANGELOG notes ✅
├─ Create GitHub release ✅
└─ Tag created: v1.1.0

Result:
├─ main branch updated
├─ GitHub release published
├─ Installable via one-line command
└─ Ready for announcements

Hotfix Flow

Critical production bug discovered:

Developer's machine:
git checkout dev
git pull origin dev
git checkout -b hotfix/critical-installer-bug
# Make minimal fix
git commit -m "fix(installer): resolve critical Windows path issue"
git push -u origin hotfix/critical-installer-bug

GitHub:
Create PR: hotfix/critical-installer-bug → dev
↓
pr-into-dev.yml runs (expedited review)
↓
Merge to dev
↓
Immediately create PR: dev → main
↓
dev-to-main.yml runs (fast-track)
↓
Merge to main
↓
Create hotfix release: v1.0.1

Branch Protection Configuration

Configure Main Branch Protection

  1. Go to Settings → Branches → Add rule
  2. Branch name pattern: main
  3. Enable:
    • ✅ Require a pull request before merging
      • ✅ Require approvals: 1 (if team)
      • ✅ Dismiss stale reviews
      • ✅ Require review from Code Owners
    • ✅ Require status checks to pass before merging
      • ✅ Require branches to be up to date
      • Add required checks:
        • quality-gates
        • production-build
        • validate-release-pr
    • ✅ Require conversation resolution before merging
    • ✅ Require linear history
    • ✅ Do not allow bypassing the above settings
  4. Under "Rules applied to everyone including administrators":
    • ✅ Restrict deletions
    • ✅ Block force pushes
  5. Save changes

Configure Dev Branch Protection

  1. Go to Settings → Branches → Add rule
  2. Branch name pattern: dev
  3. Enable:
    • ✅ Require a pull request before merging
      • Require approvals: 0 (can be 1 if team)
    • ✅ Require status checks to pass before merging
      • Add required checks:
        • quality-gates
        • validate-pr
    • ✅ Require linear history
    • ✅ Do not allow bypassing the above settings
  4. Under "Rules applied to everyone including administrators":
    • ✅ Restrict deletions
    • ✅ Block force pushes
  5. Save changes

Commit Message Guidelines

ClaudeForge uses Conventional Commits format.

Format

<type>(<scope>): <subject>

<body>

<footer>

Type (Required)

  • feat - New feature
  • fix - Bug fix
  • docs - Documentation only
  • style - Code style (formatting, semicolons)
  • refactor - Code change (neither fix nor feature)
  • perf - Performance improvement
  • test - Add/update tests
  • build - Build system or dependencies
  • ci - CI/CD configuration
  • chore - Other changes (no src/test changes)
  • revert - Revert previous commit

Scope (Optional but Recommended)

  • installer - Installation scripts
  • skill - Python skill modules
  • command - Slash commands
  • agent - Guardian agent
  • docs - Documentation
  • ci - CI/CD workflows
  • workflows - GitHub Actions

Subject (Required)

  • Use imperative mood: "add" not "added" or "adds"
  • Don't capitalize first letter
  • No period at the end
  • Maximum 50 characters

Body (Optional)

  • Explain what and why vs. how
  • Wrap at 72 characters
  • Separate from subject with blank line

Footer (Optional)

  • Reference issues: Closes #123, Fixes #456
  • Breaking changes: BREAKING CHANGE: description

Examples

Good:

feat(installer): add Windows PowerShell support

Add install.ps1 script for Windows users with equivalent
functionality to install.sh bash script.

Closes #42

Good:

fix(skill): correct template selection logic

Fix bug where wrong template was selected for TypeScript
projects. The analyzer was not correctly detecting tsconfig.json.

Fixes #156

Good:

docs: update installation troubleshooting guide

Add common installation issues based on user feedback
from issues #78, #82, and #91.

Bad:

Added new feature
  • Missing type and scope
  • Wrong tense (should be "add")
  • Vague subject

Bad:

fix: Fixed the bug
  • Capitalized subject
  • Unnecessary word "the"
  • No details on what bug

PR Title Requirements

PR titles MUST follow Conventional Commits format.

Valid examples:

  • feat(installer): add Windows PowerShell support
  • fix(skill): correct Python syntax validation
  • docs: update installation guide
  • refactor(analyzer): simplify project detection
  • ci: add Python dependency updates to dependabot

Invalid examples:

  • Add new feature ❌ Missing type/scope
  • Fixed bug ❌ Wrong tense, no scope
  • Update docs ❌ Missing colon
  • FEAT: Add feature ❌ Uppercase type
  • feat: Add feature. ❌ Period at end

Validation:

  • pr-into-dev.yml workflow validates PR title format
  • Fails if format is incorrect
  • Auto-comments with fix instructions

Merge Strategies

ClaudeForge uses Squash and Merge exclusively.

Why Squash?

✅ Linear history - Easy to understand and navigate ✅ Clean log - One commit per feature/fix ✅ Easy revert - Revert entire feature with one command ✅ Better releases - Clear association between features and versions

How it Works

When merging PR with multiple commits:

Before merge (feature branch):

feat: add template A
fix: correct typo
feat: add template B
refactor: simplify code
test: add unit tests

After merge (dev branch):

feat(skill): add Rust templates (#42)

- Add Rust template A
- Add Rust template B
- Simplify template selection
- Add unit tests

Co-authored-by: Developer <dev@example.com>

Merge Commit Message

Automatically generated:

  • Title: From PR title (Conventional Commits format)
  • Body: From PR description
  • Footer: PR number, co-authors

Git Commands Cheat Sheet

Start New Feature

# Update dev
git checkout dev
git pull origin dev

# Create feature branch
git checkout -b feature/my-feature

# Make changes and commit
git add .
git commit -m "feat(scope): add feature"

# Push to GitHub
git push -u origin feature/my-feature

Update Feature Branch with Latest Dev

# While on feature branch
git checkout dev
git pull origin dev
git checkout feature/my-feature
git rebase dev

# If conflicts, resolve and continue
git rebase --continue

# Force push (rebase rewrites history)
git push --force-with-lease origin feature/my-feature

Sync Fork (if contributing from fork)

# Add upstream remote (once)
git remote add upstream https://github.com/alirezarezvani/ClaudeForge.git

# Update from upstream
git fetch upstream
git checkout dev
git merge upstream/dev
git push origin dev

Rename Branch

# Rename current branch
git branch -m new-branch-name

# Push with new name
git push -u origin new-branch-name

# Delete old branch on remote
git push origin --delete old-branch-name

Delete Merged Branches

# Delete local branch after merge
git branch -d feature/my-feature

# Delete remote branch
git push origin --delete feature/my-feature

# Prune deleted remote branches
git fetch --prune

Common Scenarios

Scenario 1: Feature PR Rejected by Workflow

Problem: PR validation fails with "Invalid branch name"

Solution:

# Rename branch
git branch -m feature/correct-name

# Force push
git push --force-with-lease origin feature/correct-name

# Update PR with new branch

Scenario 2: Need to Update PR Title

Problem: PR title doesn't follow Conventional Commits

Solution:

  1. Go to PR page on GitHub
  2. Click "Edit" next to PR title
  3. Update to format: type(scope): description
  4. Save
  5. Workflow re-runs automatically

Scenario 3: Forgot to Update CHANGELOG.md

Problem: dev-to-main warns CHANGELOG.md not updated

Solution:

# On dev branch
git checkout dev
git pull origin dev

# Edit CHANGELOG.md
# Add version entry under [Unreleased] or create new [1.1.0] section

git add CHANGELOG.md
git commit -m "docs: update CHANGELOG for v1.1.0"
git push origin dev

# PR to main will now pass CHANGELOG check

Scenario 4: Emergency Hotfix Needed

Problem: Critical bug in production (main)

Solution:

# Create hotfix from dev (not main)
git checkout dev
git pull origin dev
git checkout -b hotfix/critical-bug

# Make minimal fix
git add .
git commit -m "fix(installer): resolve critical security issue"
git push -u origin hotfix/critical-bug

# Create PR to dev, get fast-track approval
# After merge to dev, immediately create PR dev → main
# After merge to main, create hotfix release v1.0.1

Scenario 5: Multiple Features in Development

Problem: Need to work on feature B while feature A is in review

Solution:

# Feature A already in PR
git checkout dev
git pull origin dev

# Start feature B from latest dev
git checkout -b feature/feature-b

# Work independently
# Both PRs can be reviewed in parallel
# Merge order doesn't matter (both target dev)

Best Practices

✅ Do

  • ✅ Create descriptive branch names
  • ✅ Follow Conventional Commits format
  • ✅ Link issues in PR description
  • ✅ Update CHANGELOG.md for releases
  • ✅ Keep feature branches short-lived (< 1 week)
  • ✅ Sync with dev frequently
  • ✅ Write clear commit messages
  • ✅ Test locally before pushing
  • ✅ Respond to review comments
  • ✅ Delete merged branches

❌ Don't

  • ❌ Commit directly to main or dev
  • ❌ Force push to main or dev
  • ❌ Merge without quality gates passing
  • ❌ Use vague commit messages
  • ❌ Include unrelated changes in PR
  • ❌ Commit secrets or sensitive data
  • ❌ Leave stale branches unmerged
  • ❌ Skip code review
  • ❌ Bypass branch protection (even admins)
  • ❌ Merge without linked issue (for features/fixes)

Related Documentation

Questions?

Issues: Report at GitHub Issues

Discussions: Ask in GitHub Discussions