git_branching_strategy_naming_convention.md

🌳 Git Branching Strategy & Naming Convention

This document defines the official branching strategy and naming conventions for this repository.

The goal is to keep the workflow clean, predictable, and scalable, while making collaboration and CI/CD easier.

---

🎯 General Rules

• All branch names must be lowercase
• Use kebab-case (-) for words
• Use English only
• One purpose per branch
• Delete branches after merge

General format:

<type>/<short-description>

Optional (recommended if using an issue tracker):

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

---

🌱 Main Branches

Branch	Purpose
main	Production-ready code
develop (optional)	Integration branch for features

If using Trunk-Based Development, only main is required.

---

🌿 Branch Types

🚀 feature/

Used for new functionality.

Examples:

feature/user-authentication
feature/123-add-login-form
feature/payment-integration

---

🐛 fix/

Used for bug fixes.

Examples:

fix/login-redirect-loop
fix/456-crash-on-startup

fix/ is preferred over bug/ to avoid duplication.

---

🧹 chore/

Used for maintenance tasks that don’t affect app behavior.

Includes:

• Dependency updates
• Configuration changes
• Scripts
• Tooling

Examples:

chore/update-dependencies
chore/eslint-config

---

🔧 refactor/

Used for internal code improvements without changing behavior.

Examples:

refactor/auth-service
refactor/simplify-api-layer

---

🧪 test/

Used for adding or updating tests.

Examples:

test/user-service
test/e2e-checkout-flow

---

🚑 hotfix/

Used for critical production issues.

Examples:

hotfix/payment-failure-prod
hotfix/security-patch

Hotfix branches are created from main and merged back into main (and develop if used).

---

📦 release/

Used to prepare a new production release.

Examples:

release/v1.4.0
release/2026-01

Includes:

• Version bump
• Changelog
• Final QA fixes

---

🛠 Creating a Branch

From main:

git checkout main
git pull
git switch -c feature/user-profile-page

---

❌ Invalid Branch Names (Do Not Use)

Feature/LoginPage
bugfix123
fix login
feature_add_login

---

✅ Good Examples

feature/add-user-avatar
fix/navbar-overflow
chore/update-node-versions
refactor/auth-middleware
test/payment-webhooks
hotfix/stripe-prod-error

---

🧠 Best Practices

• Keep branches short-lived
• Open pull requests early
• Keep PRs focused and small
• Always link PRs to issues if available
• Enable branch protection on main

---

📌 Recommended Pairing

This branching strategy works best when combined with:

• Conventional Commits
• Pull Request templates
• Automated CI/CD pipelines

---

✅ This document is the source of truth for branch naming in this repository.