Establishing a Team Branch Naming Convention

Establishing a Team Branch Naming Convention

A branch naming convention is only effective if the entire team follows it consistently. This guide covers how to choose, document, and enforce a convention that works for your team's size, tooling, and workflow.

Decision Framework

Answer these questions to determine your ideal convention:

Question	Impact
Do you use an issue tracker?	Determines if {ticket} is in the template
Which tracker? (JIRA/GitHub/Linear)	Determines ticket format (PROJ-123 vs #123 vs ENG-123)
Do you follow Gitflow?	Determines required type prefixes
How many teams share the repo?	Determines if team namespacing is needed
Do you deploy per-branch?	Determines naming constraints for CI/CD
What language ecosystem?	Influences convention choice (kebab vs snake)

Recommended Starting Convention

For most teams, this convention works well:

{type}/{ticket}-{short-description}

With these rules:

• Types: feature, bugfix, hotfix, release, chore, docs, test, refactor
• Convention: kebab-case, lowercase
• Max length: 80 characters
• Ticket: Required (from your issue tracker)
• Description: 2-5 words, action-oriented

Documentation Template

Add this to your CONTRIBUTING.md:

## Branch Naming

All branches must follow this pattern:
\`{type}/{ticket}-{description}\`

**Types:** feature, bugfix, hotfix, release, chore
**Examples:**
- feature/AUTH-123-add-sso-login
- bugfix/BUG-456-fix-timeout
- hotfix/v2.1.1-fix-payment

Enforcement Strategies

1. Git hooks — A pre-push hook can validate branch names against a regex pattern before allowing the push
2. CI checks — Add a pipeline step that fails if the branch name doesn't match the convention
3. Branch protection rules — Some platforms allow branch name pattern requirements
4. Code review — Include branch naming in your PR checklist
5. Tooling — Use this Git Branch Name Generator as the team's standard tool for creating branch names

Migrating from Inconsistent Naming

If your repo already has inconsistently named branches, do not rename existing branches (this disrupts open PRs and CI). Instead, announce the new convention with a start date, add enforcement for new branches only, and let old branches age out naturally as they are merged or deleted.