Conventional Commits

Structure commit messages using the Conventional Commits specification for clear, consistent, and machine-readable commit history.

When to Use

• Drafting commit messages before starting coding
• Reviewing commit message quality
• Establishing team commit message conventions
• Creating automated changelogs or version management

Core Principles

Commit messages must follow the Conventional Commits specification: https://www.conventionalcommits.org/en/v1.0.0/

Format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Commit Types

Type	Description
feat	A new feature
fix	A bug fix
docs	Documentation only changes
style	Code style changes (formatting, semi-colons, etc.) - no code logic change
refactor	Code changes that neither fix a bug nor add a feature
perf	Performance improvements
test	Adding or updating tests
build	Build system or external dependencies changes
ci	CI configuration changes and scripts
chore	Other changes that don't modify src or test files
revert	Reverts a previous commit

Format Rules

Header

• Format: <type>[optional scope]: <description>
• Description rules:
  • Must be in imperative, present tense (e.g., "add feature" not "added feature" or "adds feature")
  • No capitalization at the start
  • No period at the end
  • Keep concise (typically under 50 characters total)

feat: add dark mode toggle
fix: remove blocking overlay on login button
feat(auth): upgrade OAuth client library

Body

• Bulleted list detailing each specific change or requirement
• Provide context on what and why, not just how
• Every detail from the intent should be captured as a bullet point
• Each bullet point should also be in imperative mood
• Wrap at 72 characters

feat(ui): add dark mode toggle to header

- create new theme toggle button component
- implement dark mode state management in React context
- update Tailwind configuration with dark theme color palette

Footer

• Use for breaking changes and issues references
• Breaking changes MUST be in the footer and start with BREAKING CHANGE:
• May reference issues using a format like Closes #123 or Related to #456

feat(api): change return type

BREAKING CHANGE: Return type changed from string to object

Closes #123

Scope

• Optional part of the commit header
• Enclosed in parentheses after the type
• Identifies the part of the codebase affected
• Examples: auth, ui, api, database, docs

feat(auth): add OAuth2 provider support
fix(ui): correct alignment in navbar

Examples

Feature with multiple changes

feat(ui): add dark mode toggle to header

- create new theme toggle button component
- implement dark mode state management in React context
- update Tailwind configuration with dark theme color palette
- add CSS transitions for theme switching
- persist theme preference in local storage

Bug fix

fix(auth): remove blocking overlay on login button

- adjust z-index of the overlay div to sit behind the button
- ensure pointer-events do not intercept clicks on the login CTA

Documentation

docs: update installation instructions

- clarify dependencies for Node.js 18+
- add troubleshooting section for Windows users
- update examples with latest API changes

Breaking change

feat(api): migrate to REST v2 endpoints

BREAKING CHANGE: All API endpoints prefixed with /api/v2
- old endpoints will still be available until version 3.0
- update client SDKs to use new endpoint structure
- update authentication middleware
- update API documentation

Refactor

refactor(database): replace ORM with raw SQL queries

- improve query performance by 40%
- reduce bundle size by 15%
- add query result caching layer
- update error handling for database operations

Common Mistakes to Avoid

❌ Wrong tense

feat: added dark mode
feat: adds dark mode

✅ Correct

feat: add dark mode

❌ Capitalization or period in header

feat: Add dark mode toggle.
feat(add dark mode toggle)

✅ Correct

feat: add dark mode toggle

❌ Missing context in body

fix: remove overlay

- fix z-index

✅ Correct

fix: remove blocking overlay on login button

- adjust z-index of the overlay div to sit behind the button
- ensure pointer-events do not intercept clicks on the login CTA

Quick Reference

Type	Template
feat	feat: <short description>
fix	fix: <short description>
docs	docs: <short description>
style	style: <short description>
refactor	refactor: <short description>
perf	perf: <short description>
test	test: <short description>
build	build: <short description>
ci	ci: <short description>
chore	chore: <short description>
revert	revert: <original commit message>

---

Source: Conventional Commits