Conventional Commit
Follow the Conventional Commits specification for all commits.
Preconditions
Validate branch
Run git rev-parse --abbrev-ref HEAD.
If on main or master, stop and ask the user to create a feature branch.
Branch names should follow: <TICKET_PREFIX>-<number>-<kebab-case-description> (e.g., ENG-1333-migrate-review-flow). If invalid, ask the user to rename the branch.
Conventional Commits Spec
The commit message format:
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]Types (required)
| Type | Purpose |
|---|---|
feat | A new feature (correlates with MINOR in SemVer) |
fix | A bug fix (correlates with PATCH in SemVer) |
docs | Documentation only changes |
style | Changes that do not affect meaning (whitespace, formatting) |
refactor | Code change that neither fixes a bug nor adds a feature |
perf | Code change that improves performance |
test | Adding or correcting tests |
build | Changes to build system or external dependencies |
ci | Changes to CI configuration files and scripts |
chore | Other changes that don't modify src or test files |
Scope (optional)
A noun describing the section of codebase affected, in parentheses:
feat(parser): add ability to parse arraysfix(auth): resolve token expiration bug
Breaking Changes
Append ! after type/scope OR add BREAKING CHANGE: footer:
feat(api)!: remove deprecated endpoints
BREAKING CHANGE: The /v1/users endpoint has been removed. Use /v2/users instead.Breaking changes correlate with MAJOR in SemVer.
Steps
- Review current state
git status git diff git log -1 --oneline - Group changes logically - prefer multiple small commits over one large commit
- Create commits For each logical group: Option A: Use git commit directly (recommended for agents):
git commit -m "feat(auth): add OAuth2 support"Multi-line with body:git commit -m "feat(api): add pagination to list endpoints" \ -m "Implements cursor-based pagination for all list endpoints." \ -m "BREAKING CHANGE: Response format changed from array to object with data/meta keys."Option B: Usegit-cznon-interactive mode (streamich/git-cz, not standard cz):npx git-cz --non-interactive --type=feat --scope=auth --subject="add OAuth2 support"With body/breaking changes:npx git-cz --non-interactive \ --type=feat \ --scope=api \ --subject="add pagination to list endpoints" \ --body="Implements cursor-based pagination for all list endpoints" \ --breaking="Response format changed from array to object with data/meta keys"Note: The standardnpx cz(commitizen/cz-cli) is interactive-only and cannot be used by agents. Usegit commitornpx git-cz --non-interactiveinstead.
- Stage relevant files or hunks - Commit using Conventional Commit format
- Push the branch
git push -u origin HEAD # if no upstream git push # otherwise
Commit Message Guidelines
- Description: Use imperative mood ("add" not "added" or "adds")
- Description: Lowercase, no period at end
- Body: Explain what and why, not how
- Footer: Reference issues (
Fixes #123,Closes #456)
Notes
- Do not commit secrets, credentials, or environment files
- Describe intent and impact, not implementation detail
- When in doubt, split commits
- This skill does not perform rebases, squashes, or force pushes