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

SemVer-Mapped Core Types

Use these types when they match the change; they are the only types with implicit SemVer meaning in the specification:

• 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 changes
• style: - Code style changes (formatting, missing semicolons, etc.)
• refactor: - Code refactoring without bug fixes or new features
• perf: - Performance improvements
• test: - Adding or updating tests
• build: - Build system or external dependencies changes
• ci: - CI/CD configuration changes
• chore: - Other changes that don't modify src or test files
• revert: - 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

Style recommendations:

• Use imperative mood ("add feature" not "added feature" or "adds feature")
• Don't capitalize the first letter
• No period at the end
• Prefer 72 characters or fewer (including type and scope)
• Recommended: 50 characters or fewer for better readability

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

The specification also treats BREAKING-CHANGE: as a synonymous footer token; prefer BREAKING CHANGE: unless a project convention says otherwise.

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

1. Always use a type - Every commit must start with a type followed by a colon and space
2. Use imperative mood - Write as if completing the sentence "If applied, this commit will..."
3. Be specific - The description should clearly communicate what changed
4. Keep it focused - One logical change per commit
5. Use scopes when helpful - Scopes help categorize changes within a codebase
6. 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