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](https://www.conventionalcommits.org/en/v1.0.0/)