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