Conventional Commits
Format all commit messages according to the Conventional Commits specification. This enables automated changelog generation, semantic versioning, and better commit history.
Format Structure
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
Commit Types
Required Types
feat:
- A new feature (correlates with MINOR in Semantic Versioning)fix:
- A bug fix (correlates with PATCH in Semantic Versioning)
Common Additional Types
docs:
- Documentation only changesstyle:
- Code style changes (formatting, missing semicolons, etc.)refactor:
- Code refactoring without bug fixes or new featuresperf:
- Performance improvementstest:
- Adding or updating testsbuild:
- Build system or external dependencies changesci:
- CI/CD configuration changeschore:
- Other changes that don't modify src or test filesrevert:
- Reverts a previous commit
Scope
An optional scope provides additional contextual information about the section of the codebase:
feat(parser): add ability to parse arrays
fix(auth): resolve token expiration issue
docs(readme): update installation instructions
Description
- Must immediately follow the colon and space after the type/scope
- Use imperative mood ("add feature" not "added feature" or "adds feature")
- Don't capitalize the first letter
- No period at the end
- Keep it concise (typically 50-72 characters)
Body
- Optional longer description providing additional context
- Must begin one blank line after the description
- Can consist of multiple paragraphs
- Explain the "what" and "why" of the change, not the "how"
Breaking Changes
Breaking changes can be indicated in two ways:
1. Using !
in the type/scope
feat!: send an email to the customer when a product is shipped
feat(api)!: send an email to the customer when a product is shipped
2. Using BREAKING CHANGE footer
feat: allow provided config object to extend other configs
BREAKING CHANGE: extends
key in config file is now used for extending other config files
3. Both methods
chore!: drop support for Node 6
BREAKING CHANGE: use JavaScript features not available in Node 6.
Examples
Simple feature
feat: add user authentication
Feature with scope
feat(auth): add OAuth2 support
Bug fix with body
fix: prevent racing of requests
Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.
Remove timeouts which were used to mitigate the racing issue but are
obsolete now.
Breaking change
feat!: migrate to new API client
BREAKING CHANGE: The API client interface has changed. All methods now
return Promises instead of using callbacks.
Documentation update
docs: correct spelling of CHANGELOG
Multi-paragraph body with footers
fix: prevent racing of requests
Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.
Remove timeouts which were used to mitigate the racing issue but are
obsolete now.
Reviewed-by: Z
Refs: #123
Guidelines
- Always use a type - Every commit must start with a type followed by a colon and space
- Use imperative mood - Write as if completing the sentence "If applied, this commit will..."
- Be specific - The description should clearly communicate what changed
- Keep it focused - One logical change per commit
- Use scopes when helpful - Scopes help categorize changes within a codebase
- Document breaking changes - Always indicate breaking changes clearly
Semantic Versioning Correlation
fix:
→ PATCH version bump (1.0.0 → 1.0.1)feat:
→ MINOR version bump (1.0.0 → 1.1.0)- BREAKING CHANGE → MAJOR version bump (1.0.0 → 2.0.0)
When to Use
Use this format for:
- All git commits
- Commit message generation
- Pull request merge commits
- When the user asks about commit messages or git commits
Common Mistakes to Avoid
❌
Added new feature
(past tense, capitalized)
✅
feat: add new feature
(imperative, lowercase)
❌
fix: bug
(too vague)
✅
fix: resolve null pointer exception in user service
❌
feat: add feature
(redundant)
✅
feat: add user profile page
❌
feat: Added OAuth support.
(past tense, period)
✅
feat: add OAuth support
