Thomashighbaugh/conventional-commit

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