Branch Naming Conventions

Consistent branch naming makes it easier to understand what's being worked on, automate workflows, and maintain a clean repository.

Why Naming Conventions?

Good names help with:

Benefit	Example
Clarity	feature/user-auth vs stuff
Sorting	All features grouped together
Automation	CI can detect branch type
Communication	Team knows what's in progress
Cleanup	Easy to identify stale branches

Common Naming Patterns

Type Prefixes

feature/    - New features
bugfix/     - Bug fixes
hotfix/     - Urgent production fixes
release/    - Release preparation
docs/       - Documentation
test/       - Test additions
refactor/   - Code refactoring
chore/      - Maintenance tasks

Full Format

<type>/<issue-id>-<short-description>

Examples:
feature/AUTH-123-add-login
bugfix/BUG-456-fix-redirect
hotfix/SEC-789-patch-vulnerability
docs/update-api-reference

Alternative Formats

# With username
alice/feature/user-auth

# With date
2025-01/feature/user-auth

# Just description (simpler teams)
add-user-authentication

Naming Rules

Use Lowercase

✅ feature/user-auth ❌ Feature/User-Auth ❌ FEATURE/USER-AUTH

Use Hyphens, Not Spaces or Underscores

✅ feature/user-authentication ❌ feature/user_authentication ❌ feature/user authentication (invalid)

Be Descriptive But Concise

✅ feature/add-user-login ❌ feature/f1 (too vague) ❌ feature/add-the-user-login-feature-that-allows-users-to-sign-in (too long)

Include Issue Reference

✅ feature/AUTH-123-add-login ✅ bugfix/issue-456-fix-null

Makes it easy to find related issues/PRs.

Type-Specific Guidelines

Feature Branches

feature/user-authentication
feature/AUTH-123-add-oauth
feature/shopping-cart

Purpose: New functionality

Bugfix Branches

bugfix/login-redirect-loop
bugfix/BUG-456-null-pointer
bugfix/fix-memory-leak

Purpose: Non-urgent bug fixes

Hotfix Branches

hotfix/security-patch
hotfix/SEC-789-xss-vulnerability
hotfix/critical-payment-bug

Purpose: Urgent production fixes

Release Branches

release/1.2.0
release/v2.0.0-beta
release/2025-q1

Purpose: Prepare for release

Documentation Branches

docs/api-reference
docs/update-readme
docs/add-contributing-guide

Purpose: Documentation only

Team Examples

Simple Team

main
feature/add-login
feature/shopping-cart
bugfix/fix-navbar

With Issue Tracking

main
develop
feature/JIRA-123-user-auth
feature/JIRA-456-cart
bugfix/JIRA-789-login-fix

With Usernames

main
alice/feature/user-auth
bob/bugfix/login-fix
carol/feature/checkout

Automation with Naming

Branch Protection

Protect based on patterns:

# GitHub branch protection
branches:
  - main
  - release/*

CI/CD Triggers

# GitHub Actions
on:
  push:
    branches:
      - main
      - 'feature/**'
      - 'release/**'

jobs:
  deploy-staging:
    if: startsWith(github.ref, 'refs/heads/feature/')
    # Deploy features to staging

  deploy-production:
    if: github.ref == 'refs/heads/main'
    # Deploy main to production

Auto-labeling PRs

# Based on branch prefix
- head-branch: ^feature/
  label: feature
- head-branch: ^bugfix/
  label: bug
- head-branch: ^hotfix/
  label: urgent

Long-Running Branches

Permanent Branches

main        - Production code
develop     - Integration branch
staging     - Pre-production testing

Temporary Branches

feature/*   - Short-lived (days)
bugfix/*    - Short-lived (days)
release/*   - Limited duration (weeks)

Branch Lifecycle

Creation

# Create with meaningful name
git checkout -b feature/AUTH-123-add-login

During Work

# Keep updated
git pull origin main
git rebase main  # or merge

After Merge

# Delete locally
git branch -d feature/AUTH-123-add-login

# Delete remotely
git push origin --delete feature/AUTH-123-add-login

Viewing Branches

List by Pattern

# All feature branches
git branch --list 'feature/*'

# Remote features
git branch -r --list 'origin/feature/*'

Sort by Date

# Most recent first
git branch --sort=-committerdate

Common Mistakes

Too Vague

❌ fix ❌ update ❌ test ❌ my-branch

✅ bugfix/fix-login-validation ✅ feature/add-password-reset

Too Personal

❌ johns-stuff ❌ wip ❌ temp

✅ feature/TICKET-123-user-profile

No Convention

❌ Mixed styles in same repo:

Feature/add-login
bugfix_fix_logout
ADD-FEATURE
my feature branch

Documenting Conventions

Create a CONTRIBUTING.md with guidelines like:

Branch Naming Format:

type/ticket-id-description

Types:

• feature/ - New features
• bugfix/ - Bug fixes
• hotfix/ - Urgent fixes
• docs/ - Documentation

Examples:

• feature/AUTH-123-add-oauth
• bugfix/BUG-456-fix-null
• docs/update-api-docs

Rules:

• Use lowercase
• Use hyphens (not underscores)
• Include ticket ID when available

Summary

• Use consistent prefixes (feature/, bugfix/, etc.)
• Use lowercase with hyphens
• Include issue/ticket references
• Keep names descriptive but concise
• Delete branches after merging
• Document conventions for team
• Leverage naming for automation

In the next lesson, we'll learn about keeping a clean Git history.