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  # Edit last 3 commits

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