Git Branch Naming Convention

Contract

Every git branch name MUST be <type>/<description>, where <type> is exactly one of five fixed words — feature, fix, chore, docs, release — and the description is lowercase-hyphenated intent. Apply this whenever you name, create, or rename a branch for any kind of work.

Rules

1. Shape. A branch name is <type>/<description>. The first path segment

(everything before the first /) is the type; everything after is the description. There is exactly one type segment.

1. The type is exactly one of five words — no others ever:

feature · fix · chore · docs · release

Every kind of work collapses into one of these five. Do not invent, abbreviate, or borrow a sixth prefix from any other convention (including Conventional Commits).

1. feature/ — new functionality. New capability, new endpoint, new screen,

new behavior the product did not have before. Use the full word feature, never the abbreviation feat.

1. fix/ — correcting broken behavior. Bug, crash, regression, data

corruption, security patch, and urgent production incidents all map here. Never use bugfix/, hotfix/, bug/, patch/, or security/ — urgency and severity do NOT change the prefix.

1. chore/ — non-shipping maintenance. Refactors, performance tuning, adding

or updating tests, CI/CD pipelines, build scripts, dependency bumps, formatting/lint, renames, configuration, and tooling all map here. Never use refactor/, perf/, performance/, test/, tests/, ci/, cicd/, build/, style/, format/, deps/, dependencies/, or config/.

1. docs/ — documentation only. README, code comments, changelog,

architecture notes, guides, API reference. A change that touches only prose is docs/, even if it "fixes" a typo (it is not a fix/) and even if it relates to a release (it is not a release/).

1. release/<version> — cutting a versioned release. The description is the

version number itself, e.g. release/2.1.0. Do not put descriptive words after release/; the version is the description.

1. Description format:

• lowercase only — no uppercase letters anywhere.
• separate words with single hyphens — never spaces, underscores, dots, or

camelCase.

• describe the intent in words; a bare ticket id (PROJ-481) is NOT a valid

description on its own — add words even if you also include the id.

• never encode a username, hostname, machine, or date.
• keep it short (a few words).

Worked examples (BEFORE = base default → AFTER = conforming)

Rule 3 — full word feature:

• Task: add Google OAuth sign-in.
• BEFORE: feat/google-oauth (abbreviated, Conventional-Commits habit)
• AFTER: feature/google-oauth

Rule 4 — bug is fix, not bugfix:

• Task: null-pointer crash on checkout when the cart is empty.
• BEFORE: bugfix/checkout-null-pointer
• AFTER: fix/null-pointer-on-empty-cart

Rule 4 — urgent production incident is still fix:

• Task: production auth service is crashing, patch now.
• BEFORE: hotfix/auth-crash
• AFTER: fix/auth-service-crash

Rule 4 — security patch is still fix:

• Task: patch a SQL-injection hole in the search handler.
• BEFORE: security/sql-injection-search
• AFTER: fix/sql-injection-in-search

Rule 5 — refactor is chore:

• Task: remove duplicated code in the payments module, no behavior change.
• BEFORE: refactor/payments-dedupe
• AFTER: chore/payments-dedupe

Rule 5 — performance work is chore:

• Task: speed up the slow dashboard query.
• BEFORE: perf/dashboard-query
• AFTER: chore/speed-up-dashboard-query

Rule 5 — tests-only is chore:

• Task: add unit tests for the billing service, no product code.
• BEFORE: test/billing-service
• AFTER: chore/billing-service-tests

Rule 5 — CI work is chore:

• Task: update GitHub Actions to run on Node 20.
• BEFORE: ci/node-20
• AFTER: chore/ci-node-20

Rule 5 — dependency bumps are chore:

• Task: bump all npm dependencies.
• BEFORE: deps/bump-all
• AFTER: chore/bump-dependencies

Rule 6 — README typo is docs, not fix:

• Task: fix a typo in the README.
• BEFORE: fix/readme-typo
• AFTER: docs/readme-typo

Rule 7 — release description is the version:

• Task: cut version 2.1.0.
• BEFORE: release/version-2.1.0 or feature/v2-release
• AFTER: release/2.1.0

Rule 8 — words, not just a ticket id:

• Task: ticket PROJ-481, fix a broken password-reset email.
• BEFORE: PROJ-481 or fix/PROJ-481
• AFTER: fix/password-reset-email

Rule 8 — hyphens and lowercase:

• Task: add a real-time notifications center.
• BEFORE: feature/Real_Time_Notifications or feature/realTimeNotifications
• AFTER: feature/real-time-notifications

Edge cases & exceptions

• Security / hotfix / regression — all still fix/. The five-word vocabulary

has no severity axis; a P0 production security hotfix and a cosmetic bug share the fix/ prefix.

• Refactor vs. feature — a pure refactor with no new user-facing behavior is

chore/, not feature/. If the change adds capability, it is feature/.

• Tests added alongside a feature — name the branch for the primary work. A

branch whose only purpose is tests is chore/; tests shipped with a new feature live on that feature/ branch.

• Changelog / release notes — editing the CHANGELOG or release notes is a

documentation change → docs/, even though it accompanies a release. Only the act of cutting the version is release/.

• Config / tooling / build — tsconfig, eslint, Dockerfiles, Makefiles,

lockfile updates → chore/. There is no config/ or build/ prefix.

• Ticket id — you may include the id with intent words

(fix/PROJ-481-password-reset), but never the id alone.

• Release description — only the version goes after release/. No

release/2.1.0-final, no release/q3-launch — just release/2.1.0.

Do / Don't

• Do write feature/…. Don't write feat/….
• Do map every bug/crash/security/urgent fix to fix/. Don't use

bugfix/, hotfix/, bug/, patch/, or security/.

• Do map refactor/perf/test/ci/build/style/deps/config to chore/. Don't

spin up refactor/, perf/, test/, ci/, build/, style/, or deps/.

• Do use docs/ for any prose-only change. Don't call a README typo a

fix/.

• Do put the bare version after release/. Don't add words after it.
• Do join words with single hyphens, all lowercase. Don't use spaces,

underscores, dots, or camelCase.

• Do describe intent in words. Don't name a branch with only a ticket id.

Common mistakes (the base's wrong defaults)

• Reaching for Conventional-Commits types: feat/, refactor/, perf/, test/,

ci/, build/, style/ — none of these exist here; collapse them into the five.

• Encoding urgency: hotfix/, urgent/, bugfix/ instead of plain fix/.
• Treating a doc/typo fix as a fix/ instead of docs/.
• Padding release/ with words instead of the bare version number.
• camelCase, underscores, or capital letters in the description.
• Naming a branch with only a ticket id and no intent words.
• Inventing a security/ prefix for security work instead of fix/.

Quick checklist

1. Is the prefix exactly one of feature / fix / chore / docs / release?
2. New capability → feature (full word, not feat)?
3. Any kind of broken behavior, including security/hotfix → fix?
4. Any maintenance — refactor/perf/test/ci/build/deps/config → chore?
5. Prose-only change → docs?
6. Release → release/<bare-version>?
7. Description lowercase, single-hyphen, intent words, no ticket-id-only, no

username/host?