Format
<type>[(scope)]: <description>
- Type and description are lowercase
- No period at end
- Imperative mood: "add" not "added"
- Under 100 characters
- Scope is optional, use package or feature area (e.g.,
init,deploy,cli-core,deps,ci)
Release-Triggering Types
These types generate changesets and trigger npm releases:
| Type | Bump | Use for |
|---|---|---|
feat |
minor | New commands, flags, features |
fix |
patch | Bug fixes, crash fixes, incorrect output |
perf |
patch | Performance improvements |
revert |
patch | Reverting previous changes |
feat! / fix! |
major | Breaking changes (removed commands, changed flag behavior) |
Non-Release Types
These do not trigger releases or changesets:
| Type | Use for |
|---|---|
chore |
Tooling, build config, dependency updates |
refactor |
Code restructuring without behavior change |
test |
Adding or updating tests |
docs |
Documentation only |
style |
Formatting, whitespace |
build |
Build system changes |
ci |
CI/CD pipeline changes |
Decision Guide
- Does it change what users experience? Use
featorfix - Does it break existing behavior? Add
!suffix (e.g.,feat!) - Is it internal-only with no user impact? Use
chore,refactor,test, etc. - Dependency updates? Use
chore(deps)unless fixing a user-facing bug, thenfix(deps)
Examples from This Repo
feat: auto-generate changesets from PR descriptions
feat(embeddings): add projection validation using groq-js
feat(cli): inject __SANITY_STAGING__ global in staging builds
fix(init): strip filename before counting nested folders in import path
fix(deploy): stop spinner before returning from app lookup
refactor(cli-core): replace oclif ux.colorize with node:util styleText
refactor(cli): migrate from zod to zod/mini for smaller bundle size
chore: skip auto-generated changeset when one already exists
chore(ci): use squiggler-app bot as changeset commit author
chore(deps): update swc-tooling