ClaudeForge/docs/BRANCHING_STRATEGY.md

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

• GITHUB_WORKFLOWS.md - Workflow details and automation
• CONTRIBUTING.md - How to contribute
• CHANGELOG.md - Version history

---

Questions?

Issues: Report at GitHub Issues

Discussions: Ask in GitHub Discussions