Conventional Commits specification: commit types, scope, breaking changes, multi-line bodies, and tooling for enforcement.
BeforeMerge offers hundreds of code review rules, guides, and detection patterns to help your team ship better code.
Conventional Commits provide a structured format for commit messages that enables automated versioning, changelogs, and easier code review.
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]| Type | Use when | Triggers |
|---|---|---|
feat |
Adding a new feature | Minor version bump |
fix |
Fixing a bug | Patch version bump |
docs |
Documentation only | No release |
style |
Formatting, whitespace | No release |
refactor |
Code change that neither fixes nor adds | No release |
perf |
Performance improvement | Patch version bump |
test |
Adding or updating tests | No release |
build |
Build system or dependencies | No release |
ci |
CI configuration | No release |
chore |
Maintenance tasks | No release |
revert |
Reverting a previous commit | Depends on reverted type |
feat: add user avatar upload
feat(auth): implement password reset flow
fix: prevent race condition in checkout
fix(api): handle null response from payment provider
refactor: extract validation logic into shared utility
docs: update API authentication guide
perf: optimize database queries for dashboardScope indicates what part of the codebase is affected:
feat(auth): ...
fix(api): ...
refactor(db): ...
test(checkout): ...Keep scopes consistent across the project. Document valid scopes in your contributing guide.
Indicate breaking changes with ! after the type/scope or with a BREAKING CHANGE: footer:
feat!: change API response format to JSON:API
feat(api)!: remove deprecated v1 endpoints
BREAKING CHANGE: The /v1/* endpoints have been removed.
Migrate to /v2/* before upgrading.Breaking changes trigger a major version bump.
The body explains why the change was made:
fix(auth): handle expired refresh tokens gracefully
Previously, expired refresh tokens caused a 500 error.
Now we return a 401 with a clear message instructing
the client to re-authenticate.
Closes #423Enforce commit message format in CI:
// .commitlintrc.json
{
"extends": ["@commitlint/config-conventional"]
}npm install --save-dev @commitlint/cli @commitlint/config-conventionalRun commitlint on every commit:
npx husky add .husky/commit-msg 'npx --no -- commitlint --edit $1'Interactive commit message prompt:
npm install --save-dev commitizen cz-conventional-changelog
npx czAutomate version bumps and changelogs based on commit types:
{
"release": {
"branches": ["main"],
"plugins": [
"@semantic-release/commit-analyzer",
"@semantic-release/release-notes-generator",
"@semantic-release/npm",
"@semantic-release/github"
]
}
}