--- name: git-branch-naming-convention source: https://app.decimal.ai/s/git-branch-naming-convention@1/SKILL.md source_sha256: af8de4cefd47 --- # Git Branch Naming Convention ## Contract Every git branch name MUST be `/`, where `` 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 `/`. The first path segment (everything before the first `/`) is the type; everything after is the description. There is exactly one type segment. 2. **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). 3. **`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`. 4. **`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. 5. **`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/`. 6. **`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/`). 7. **`release/` — 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. 8. **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/`? 7. Description lowercase, single-hyphen, intent words, no ticket-id-only, no username/host?