branch-namer

# Branch Namer ## The Problem Branch names like `fix/dx` or `feature/billing` are technically valid but practically useless. When you scan a list of branches, you should immediately understand what each one is about without having to look up the PR or commit history. **Exception**: For investigation or exploratory tasks where the outcome isn't known upfront, it's fine to name the branch after the task/ticket (e.g., `chore/investigate-memory-leak` or `chore/PROJ-123`). The descriptive slug matters most for feature and fix branches where the intent is clear. ## Branch Name Format ```text <type>/<scope>-<descriptive-slug> ``` **Components:** - **type**: One of the conventional commit types listed below. Use the same type you'd use in the commit message. Prefer `feat` over `feature` for consistency with commit conventions. **Pick the type carefully — it controls CI/CD behavior:** | Type | Triggers Release? | Changelog | Auto-approve eligible | |------|-------------------|-----------|----------------------| | `feat` | Yes (minor bump) | Visible | No | | `fix` | Yes (patch bump) | Visible | No | | `refactor` | Yes (patch bump) | Visible | No | | `chore` | No release | Hidden | Yes* | | `test` | No release | Hidden | Yes* | | `docs` | No release | Hidden | Yes* | *Auto-approve requires `experienced-contributor` label, small PR size, and restricted file scope. Use `chore`/`test`/`docs` for changes that don't affect the shipped artifact (CI config, `.helm` charts, `package.json` scripts, test-only changes, README updates). These don't trigger a release even though they may affect production deployments. Use `refactor` only when you're restructuring code that ends up in the built/deployed application — it triggers a patch release even though nothing user-facing changed. - **scope**: A category from the project's `.commitlintrc.json` `scope-enum` list. Read this file to get the current allowed scopes. If nothing fits, use a short reasonable name. For app-specific changes, you can use a sub-path like `fix/provider-console/min-balance-issue`. - **descriptive-slug**: 3–6 words in kebab-case that describe *what* the change does. This is the part that matters most. ## How to Write the Slug The slug should answer: "What does this branch do?" in a few words. Think of it like a compressed commit message subject. **Principles:** - Lead with a verb when natural: `add-`, `close-`, `remove-`, `update-`, `handle-`, `migrate-` - Drop articles (a, an, the) and filler words - Use domain terms the team recognizes (e.g., `sequelize`, `stripe`, `managed-wallet`) - Keep it under ~50 characters total (type + scope + slug) - Don't repeat the type in the slug — `fix/auth-fix-login-redirect` → `fix/auth-login-redirect` ## Examples | PR / Task Description | Bad Branch Name | Good Branch Name | |-----------------------------------------------------|----------------------|-----------------------------------------------| | Close Sequelize connection on container dispose | `fix/dx` | `fix/dx-close-sequelize-on-dispose` | | Redirect unauthenticated users to login on /api-keys| `fix/auth` | `fix/auth-redirect-unauthenticated-to-login` | | Add Stripe payment method to billing | `feat/billing` | `feat/billing-add-stripe-payment-method` | | Handle MissingStateCookieError during auth | `fix/auth` | `fix/auth-handle-missing-state-cookie` | | Granular skip labels for security scan workflow | `chore/ci` | `chore/ci-granular-skip-labels-security` | | Use local instrumentation package in indexer | `refactor/indexer` | `refactor/indexer-use-local-instrumentation` | | Migrate deploy-web from deprecated SDL class | `refactor/sdl` | `refactor/sdl-migrate-deploy-web-generate-manifest` | | Switch notifications build from webpack to tsup | `refactor/notifications` | `refactor/notifications-switch-webpack-to-tsup` | | Add ACT support for authorizations | `feat/wallet` | `feat/wallet-add-act-authorization-support` | ## Workflow 1. **Read `.commitlintrc.json`** to get the allowed scopes for the current project 2. **Determine the type** — `feat`, `fix`, `refactor`, `chore`, `docs`, or `test`? 3. **Pick the scope** — which area of the codebase does this touch? 4. **Write the slug** — compress the task description into 3–6 kebab-case words 5. **Check the total length** — aim for under 50 characters 6. **Suggest the branch name** to the user before creating it