| name | faq |
| description | Frequently asked questions and practical guidance for implementing Conventional Commits in your workflow. |
Conventional Commits FAQ
General Questions
What is the primary goal of Conventional Commits?
The primary goal is to provide a lightweight convention on top of commit messages that makes it easier to:
- Write automated tools that act on commits
- Generate changelogs automatically
- Determine semantic version bumps automatically
- Communicate the nature of changes clearly to all stakeholders
- Trigger build and publish processes based on commit types
Why should I use Conventional Commits?
Benefits:
- Automated Tooling: Your commits become machine-readable for automated processing
- Clear History: Easy to scan and understand what changed when looking at git log
- Semantic Versioning: Automatic version bumping based on commit types
- Changelog Generation: Auto-generate release notes from commits
- Team Communication: Everyone understands the nature of changes at a glance
- Project Organization: Encourages atomic, well-thought-out commits
Does using Conventional Commits add extra work?
Initially, yes - it requires thinking about commit structure. However, it saves time by:
- Enabling automation that would otherwise require manual work
- Reducing back-and-forth communication about what changed
- Making code reviews clearer
- Reducing time spent understanding change history
Implementation Questions
How should I deal with commit messages in the initial development phase?
We recommend that you proceed as if you've already released the product. Typically someone, even if it's your fellow software developers, is using your software. They'll want to know what's fixed, what breaks, etc. Starting with Conventional Commits from day one establishes good habits.
Are the types in the commit title uppercase or lowercase?
Any casing may be used, but consistency is important. Lowercase is recommended:
✓ feat: add dark mode
✓ fix: resolve null pointer
✗ Feat: add dark mode
✗ Fix: resolve null pointer
What do I do if the commit conforms to more than one of the commit types?
Go back and make multiple commits whenever possible. Part of the benefit of Conventional Commits is its ability to drive you to make more organized commits and PRs.
Example - Avoid:
feat: add payment processing and fix calculation bug
Better - Make Two Commits:
feat: add Stripe payment integration
fix: correct order total calculation
How should I capitalize the description?
Start with lowercase (unless using parenthesis for scope):
✓ feat: add dark mode support
✓ feat(ui): add dark mode support
✗ feat: Add dark mode support
✗ feat(ui): Add dark mode support
Should I use imperative or past tense?
Always use imperative mood (command form), not past tense:
✓ feat: add user authentication
✓ fix: resolve login issue
✓ refactor: simplify request handling
✗ feat: added user authentication
✗ fix: resolved login issue
✗ refactor: simplified request handling
This matches the convention used by git itself (e.g., "revert: revert commit X").
Should I include a period at the end of the description?
No, omit the period:
✓ feat: add authentication support
✗ feat: add authentication support.
Technical Questions
How long should the description be?
Keep it concise - ideally 50 characters or less. This prevents truncation in various git tools and displays:
✓ feat: add OAuth2 authentication (40 chars)
✗ feat: add OAuth2 authentication support to the application (too long)
If you need more space, use the body.
What's the difference between scope and body?
-
Scope: Brief context about which part of the system is affected (wrapped in parenthesis)
feat(auth): add OAuth2 support
-
Body: Detailed explanation of why and how, separated by blank line
feat(auth): add OAuth2 support
Implement OAuth2 authentication flow to provide better security
and support for federated identity providers. Users can now log in
with Google, GitHub, or Microsoft accounts.
When should I include a body?
Include a body when:
- The change is complex or non-obvious
- You need to explain the "why" behind the change
- There's important context for future developers
- The change has implications for other parts of the system
Skip the body for:
- Simple, obvious changes
- Small bug fixes with clear intent
- Documentation fixes
- Basic refactoring
How do I indicate a breaking change?
Two ways:
Option 1: Use ! before the colon
feat!: drop support for Node 6
feat(api)!: change authentication flow
Option 2: Use footer
feat: change authentication flow
BREAKING CHANGE: authentication now requires OAuth2 tokens
Option 3: Both (redundant but clear)
feat!: change authentication flow
BREAKING CHANGE: authentication now requires OAuth2 tokens
Workflow Questions
Doesn't this discourage rapid development and fast iteration?
No - it discourages moving fast in a disorganized way. It helps you:
- Move fast long-term across multiple projects
- Onboard new contributors more easily
- Maintain clearer history that doesn't need future investigation
- Enable automation that would otherwise require manual processes
Fast iteration is still possible - you're just being intentional about commits.
Might Conventional Commits limit developers to thinking only in the types provided?
Conventional Commits encourages us to make more of certain types of commits (like fixes and features). The specification explicitly allows custom types, so:
mycompany: proprietary integration with our system
performance-testing: results from performance benchmarks
Your team can extend the specification based on your needs.
Can I use Conventional Commits in a squash-merge workflow?
Yes! In fact, squash-merge workflows are ideal:
- Casual contributors make any commits they want
- Lead maintainers clean up commit history when merging
- The final merged commit follows Conventional Commits
- No burden on contributors to learn the convention
This is a common workflow for open source projects.
Tooling Questions
How does this relate to SemVer?
Conventional Commits enable automatic semantic versioning:
| Commit Type | SemVer Change |
|---|
fix | PATCH (1.0.0 → 1.0.1) |
feat | MINOR (1.0.0 → 1.1.0) |
BREAKING CHANGE | MAJOR (1.0.0 → 2.0.0) |
Tools like semantic-release automatically parse commits and bump versions.
What tools support Conventional Commits?
Popular tools that support or require Conventional Commits:
- commitlint: Linter for commit messages
- semantic-release: Automatic versioning and publishing
- standard-version: Changelog generation and versioning
- gitflow: Git workflow tools
- husky: Git hooks for enforcing conventions
- conventional-changelog: Generate changelogs from commits
Can I enforce Conventional Commits?
Yes, using tools like:
commitlint - Validate commit message format
npm install --save-dev @commitlint/config-conventional @commitlint/cli
husky - Run hooks on git events
npm install husky --save-dev
husky install
Common Issues
I accidentally used the wrong commit type. What do I do?
Before Merging/Release:
Use git rebase -i to edit the commit history:
git rebase -i HEAD~3
After Release:
The cleanup will depend on your tools and processes. Ideally, you're using automation that can skip malformed commits or handle them gracefully.
I used a type not in the spec (e.g., "feet" instead of "feat")
It's not the end of the world. The commit will simply be missed by tools that are based on the spec. Automated tools won't recognize it, but it doesn't break anything. Fix it in the next commit with a rebase if important.
What if I can't follow Conventional Commits in my project?
You can still benefit from the concept:
- Use automated tools to reformat commits during merge
- Educate team members gradually about the benefits
- Start with a subset of commit types that your team agrees on
- Use commitlint to enforce the convention
Contributor Questions
Do all my contributors need to use Conventional Commits?
No! Many projects use approaches like:
- Squash merging: PRs can have any commits; the merge commit follows convention
- Commit message templates: Guide developers with templates
- Automated reformatting: Tools clean up commit history on merge
- Gradual adoption: Start with maintainers, encourage contributors over time
How do I explain Conventional Commits to my team?
Quick Explanation:
"We use a standard format for commit messages so automated tools can understand what changed. It looks like: type(scope): description"
Example:
feat(payment): add Stripe integration
Benefits:
- Automatic changelog generation
- Automatic version bumping
- Clear history for everyone
- Tools can act on commits automatically
What if someone forgets to use the convention?
Options:
- Gentle reminder: Point them to your contribution guidelines
- Automated enforcement: Use commitlint to catch it automatically
- Squash on merge: Reformat during merge to main branch
- Education: Share examples and guidelines
- Patience: Most people adopt it quickly once they see the benefits
Revert Questions
How do I handle revert commits?
The Conventional Commits spec doesn't define revert behavior explicitly. Recommended approach:
revert: let us never again speak of the noodle incident
Refs: 676104e, a215868
Or include the original type:
fix: revert incorrect authentication changes from commit a215868
This reverts commit a215868. The previous approach caused issues with
federated identity providers.
Should I revert or create a new fix commit?
Revert if:
- The commit caused significant problems
- It's a recent commit that didn't provide value
- You need to preserve that it was reverted
Create new fix if:
- The original code had the right idea but a bug
- You're fixing a side effect or unforeseen issue
- It's the cleaner approach historically
Version Compatibility
How do I version my extensions to the Conventional Commits Specification?
Use SemVer to version your extensions:
- Document what custom types your project adds
- Example:
@yourcompany/conventional-commits-config version 1.0.0
- Update versions when you add new types or change rules
License: Creative Commons - CC BY 3.0
Source: Conventional Commits v1.0.0
