Branch naming conventions

The Importance of Branch Naming Conventions

Good branch naming conventions enhance team collaboration efficiency and reduce communication costs. Clear naming allows developers to understand the purpose of a branch at a glance, avoiding merge conflicts and misoperations. Without unified standards, chaotic names like fix-bug or hotfix_login may emerge, leading to difficulties in later maintenance.

Basic Naming Principles

Branch names should be concise yet descriptive, typically using lowercase letters and hyphens. Avoid special characters, spaces, or Chinese characters to maintain compatibility with Git tools. Here are some core principles:

1. Use lowercase letters
2. Separate words with hyphens (-)
3. Include contextual information
4. Avoid excessive length (recommended no more than 5 words)
5. Reflect the branch's purpose rather than author information

Common Branch Types and Naming Patterns

Feature Development Branches

Feature branches are used for developing new functionalities, usually branched from main or develop. Naming pattern:

feature/[brief-description]-[related-issue-ID]

Examples:

# Development of a login page with Jira issue ID PROJ-123
feature/login-page-PROJ-123

# Simple feature without an issue tracking system
feature/user-profile-avatar

Bug Fix Branches

Fix branches are dedicated to resolving defects found in production or testing environments:

fix/[issue-description]-[related-issue-ID]

Practical examples:

# Fix for a non-clickable login button
fix/login-button-click-PROJ-456

# Urgent production issue fix
fix/payment-amount-calculation

Release Branches

Branches preparing for release require special marking:

release/[version-number]

Version numbers should follow semantic versioning:

release/1.2.0
release/2.0.0-rc.1

Hotfix Branches

For urgent fixes in production environments:

hotfix/[brief-description]

Typical examples:

hotfix/security-patch-cve2023
hotfix/checkout-flow-500-error

Advanced Naming Techniques

Including Environment Information

When a branch corresponds to a specific environment, include an environment identifier in the name:

feature/search-api-staging
fix/header-layout-prod

Date Tagging Method

For long-lived experimental branches, include the creation date:

experiment/new-algorithm-20230515

Team Prefixes

For large projects with multiple collaborating teams, add team identifiers:

mobile/feature/offline-mode
backend/fix/api-timeout

Integration with Automation Tools

Modern Git platforms support automatic process triggering based on branch names. For example:

# Automatically link to Jira issues
feature/PROJ-123-description

# Trigger CI/CD pipelines
build/android-beta-1.3.0

Example Naming Validation Script

Enforce naming conventions via Git hooks or CI scripts. Here’s a Node.js implementation:

// scripts/validate-branch-name.js
const branchName = require('current-git-branch')();
const patterns = [
  /^(feature|fix|hotfix|release)\/[a-z0-9-]+(\-[A-Z]+-\d+)?$/,
  /^experiment\/[a-z0-9-]+\-\d{8}$/,
  /^[a-z]+\/(feature|fix)\/[a-z0-9-]+$/
];

if (!patterns.some(regex => regex.test(branchName))) {
  console.error(`
    Invalid branch name: "${branchName}"
    Follow naming conventions like:
    - feature/login-page-PROJ-123
    - fix/button-color
    - release/1.2.0
  `);
  process.exit(1);
}

Handling Special Scenarios

Long-Term Maintenance Branches

For branches requiring long-term maintenance of older versions, clearly mark the version number:

support/v1.x
legacy/enterprise-edition

Refactoring Branches

For large-scale code refactoring, use specific markers:

refactor/auth-module
migration/webpack-to-vite

Documentation Update Branches

For pure documentation updates, use specific prefixes:

docs/api-reference-update
changelog/2023-updates

Naming Anti-Patterns

Common naming mistakes to avoid:

1. Using author names:

   johns-feature
   fix-by-mike
   

2. Vague descriptions:

   patch-1
   test-branch
   

3. Including spaces or special characters:

   my new feature
   bugfix@important
   

4. All uppercase letters:

   FEATURE/NEW-UI
   HOTFIX/CRITICAL
   

Cross-Team Collaboration Practices

Distributed teams should establish clear naming convention documents, including:

1. Prefix dictionary
2. Issue tracking system ID format
3. Environment identifier standards
4. Special branch handling processes

Example collaboration standard:

| Branch Type | Prefix     | Example               |
|-------------|------------|-----------------------|
| Feature     | feature/   | feature/cart-flow     |
| Bug Fix     | fix/       | fix/ios-crash-123     |
| Hotfix      | hotfix/    | hotfix/auth-bypass    |
| Release     | release/   | release/2.3.0         |