| name | conventional-commits |
| description | Use when writing git commit messages, reviewing commits, or setting up commit conventions. Triggers on commit, git commit, commit message, changelog, semantic versioning. |
Conventional Commits v1.0.0-beta.2
Structured commit messages that enable automated changelogs and semantic versioning.
Format
<type>[optional scope]: <description>
[optional body]
[optional footer]
Quick Reference
| Type | Purpose | SemVer Impact |
|---|
feat | New feature (MUST use for new features) | MINOR bump |
fix | Bug fix (MUST use for bug fixes) | PATCH bump |
docs | Documentation only | None |
style | Formatting, no code change | None |
refactor | Neither fix nor feature | None |
perf | Performance improvement | None |
test | Adding/fixing tests | None |
chore | Build, tooling, deps | None |
Any + BREAKING CHANGE | Breaking API change | MAJOR bump |
The 11 Specification Rules
- Commits MUST be prefixed with a lowercase type (noun:
feat, fix, etc.) followed by colon and space
feat MUST be used when a commit adds a new featurefix MUST be used when a commit represents a bug fix- Optional scope MAY follow the type in parentheses:
fix(parser):
- Description MUST immediately follow the type/scope prefix
- Longer body MAY follow after one blank line after description (may contain multiple paragraphs)
- Footer MAY follow one blank line after body (or description if no body). Multiple footers allowed using
token: value or token #value format
- Breaking changes MUST be indicated at the very beginning of the footer or body section as uppercase
BREAKING CHANGE: (or BREAKING-CHANGE:) followed by a space
- A description MUST be provided after
BREAKING CHANGE:
- Types other than
feat and fix MAY be used
! MAY be appended after type/scope (with or without scope: feat!: or feat(scope)!:) to draw attention to breaking change. BREAKING CHANGE: in footer MUST also be included when ! is used
Examples
Simple feature:
feat: add email notifications for order updates
Scoped bug fix:
fix(auth): prevent session fixation on login
Breaking change with ! and footer:
refactor(api)!: remove deprecated /v1 endpoints
Migrate all clients to /v2 before upgrading.
BREAKING CHANGE: /v1/* endpoints have been removed. Use /v2/* instead.
Breaking change without scope (using !):
feat!: drop Node 14 support
BREAKING CHANGE: minimum Node version is now 16.
Multiple footers:
feat(parser): support nested array syntax
Arrays can now contain other arrays, enabling complex
data structures in configuration files.
Reviewed-by: Alice
Closes #245
Common Mistakes
| Mistake | Correct |
|---|
Fixed bug in login | fix(auth): resolve null check on login |
feat: Fix typo | fix: correct typo in README (not a feature) |
BREAKING CHANGE without footer format | Must be at start of footer/body: BREAKING CHANGE: description |
feat!: without BREAKING CHANGE in footer | Rule 11: ! requires BREAKING CHANGE: in footer too |
| Missing blank line before body | Body MUST be separated by one blank line |
Scope with spaces feat(my scope): | Use hyphens: feat(my-scope): |
