One branch shape across every repo. Read the type and the scope from the branch name alone — no git log required.
Branch names follow Conventional Branch: a short type prefix, a /, and a kebab-case description. The type matches the commit conventions prefix that the eventual squash commit will use, so the branch name predicts the changelog entry.
Shape
<type>is one of the allowed short forms below — never the long form.<short-kebab-case-name>is lowercase, hyphen-separated, descriptive but tight (≤ 5 words is usually enough).- No issue numbers, no usernames, no dates — those belong in commit bodies and PR descriptions, not branch names.
| Good | Bad | Why |
|---|---|---|
feat/add-syslog-firewall | feature/add-syslog-firewall | Long form feature; banned. |
fix/dns-resolver-restart | bugfix/dns-resolver-restart | Long form bugfix; banned. |
chore/pin-tofu-1.10 | chore/JAC-127 | Issue ID instead of a description. |
docs/end-goal-sweep | docs/jacob-pe-friday-cleanup | Author name; irrelevant in 6 months. |
refactor/extract-vlan-helper | refactor/v2 | Vague; says nothing. |
Allowed types — short forms only
These match the Conventional Commits prefixes one-to-one. Always the short form.feat not feature. fix not bugfix. No exceptions.
| Type | Use for |
|---|---|
feat/ | New capability, integration, or significant behavioral change. Maps to feat: commit → minor version bump. |
fix/ | Bug fix, small improvement, config tweak, dependency bump. Maps to fix: commit → patch bump. |
chore/ | Maintenance that does not affect users — formatting passes, internal refactors that change no behavior, repo hygiene. |
docs/ | Documentation-only changes (README.md, docs/, *.mdx, comments). No code changes. |
refactor/ | Code restructuring that intentionally changes neither behavior nor external API. |
test/ | Adding or fixing tests without changing the code under test. |
ci/ | CI/CD workflow changes (.github/workflows/, pre-commit config, runner pinning). |
build/ | Build-system / dependency changes (flake.nix, package.json, lockfiles) that don’t fit chore. |
perf/ | Performance improvements that change neither behavior nor API. |
style/ | Pure formatting (whitespace, semicolons). Almost always swallowed into chore or refactor — rare. |
feat: → minor, fix: → patch, everything else → no version bump (per release-please defaults).
Why short forms
The aliases the long forms suggest (feature, bugfix) don’t appear in any Conventional Commits / Conventional Branch spec. Mixing both creates two parallel taxonomies that release tooling, branch protection rules, and CODEOWNERS regexes have to match independently. One canonical set keeps everything (CI, automation, AI agents, humans skimming git branch) on the same page.
The full Conventional Branch spec, including the release/ and hotfix/ types this org does not use, lives at conventional-branch.github.io. The commitlint config that enforces the matching commit prefixes is @commitlint/config-conventional.
What this connects to
Commit conventions
The matching commit prefix vocabulary. Branch type and commit type are one decision, made once.
PR conventions
PR title inherits the conventional-commit prefix from the branch.
Git transport
SSH for public, HTTPS for private. Picks transport by visibility, not by branch.
CI/CD policy
How
feat: and fix: translate into release-please version bumps once the branch merges.