Branch Naming Conventions
debt(d7/e3/b5/t3)
Closest to 'only careful code review or runtime testing' (d7). The detection_hints indicate automated=no; tools listed are git, github, gitlab — none of which enforce naming conventions by default. Poor branch names are only caught during code review or when a team member notices a confusing PR title or CI log. No linter or compiler catches this.
Closest to 'simple parameterised fix' (e3). The quick_fix describes adopting a consistent prefix pattern (feature/, fix/, hotfix/, etc.) with ticket IDs. This is a small, repeatable change — a team convention or a branch protection rule configuration — rather than a one-line code patch but also far from a cross-cutting refactor. Existing badly-named branches need renaming but it's localised work.
Closest to 'persistent productivity tax' (b5). Applies to any git context (applies_to: any). Poor naming silently taxes multiple work streams: PR reviews, CI pipeline readability, deployment dashboards, Slack notifications (as the misconception highlights). It doesn't restructure the whole system but consistently slows down team communication and tooling traceability across many workflows.
Closest to 'minor surprise' (t3). The misconception is specific: developers assume branch names are personal/local, but they surface in PR titles, CI logs, dashboards, and notifications. This is a one-edge-case surprise — the social/team visibility aspect — rather than a deep behavioural gotcha. Most developers learn this fairly quickly once they see their branch name in a Slack notification or CI dashboard.
Also Known As
TL;DR
Explanation
Common convention: type/short-description where type is feature, fix, hotfix, release, chore, refactor, or docs. Examples: feature/user-oauth-login, fix/checkout-total-rounding, hotfix/critical-xss-patch, release/2.1.0. Rules: lowercase only, hyphens not spaces (spaces are awkward in shell), descriptive but concise. Include ticket/issue number for traceability: feature/PROJ-123-user-oauth. Protected branches (main, develop, release/*) enforced via branch protection rules.
Common Misconception
Why It Matters
Common Mistakes
- Spaces in branch names: git checkout -b 'my feature' — problematic in many shell contexts.
- All changes in main/develop without feature branches — no code review, no CI isolation.
- Single-letter or cryptic names: fix/abc, wip2, test-branch.
- No type prefix — cannot distinguish features from fixes from hotfixes at a glance.
Code Examples
# Cryptic branch names:
git checkout -b paul
git checkout -b fix
git checkout -b new-stuff
git checkout -b wip-checkout
git checkout -b 'my feature branch' # Space causes problems
# In GitHub: 23 open PRs, no idea what any of them are# Clear convention: type/ticket-description
git checkout -b feature/PROJ-123-user-oauth-login
git checkout -b fix/PROJ-456-checkout-total-rounding
git checkout -b hotfix/critical-xss-in-comment-form
git checkout -b release/2.1.0
git checkout -b chore/upgrade-dependencies-march
# Enforced by CI: branch must match pattern
# ^(feature|fix|hotfix|release|chore|refactor|docs)\/[a-z0-9-]+$