Conventional Commits

Also Known As

TL;DR

Explanation

Conventional Commits defines a structured format: <type>[optional scope]: <description>. Types: feat (new feature → bumps MINOR), fix (bug fix → bumps PATCH), docs, style, refactor, test, chore, perf. Breaking changes are indicated by a ! suffix or BREAKING CHANGE: footer (→ bumps MAJOR). Example: feat(auth): add OAuth2 login via GitHub. Tools built on this format: semantic-release (automated npm/GitHub releases), git-cliff and conventional-changelog (CHANGELOG generation), and commitlint (pre-commit enforcement). For PHP projects, use cocur/slug-based tooling or the standard semantic-release with a PHP adapter. Pair with a pre-commit hook (Husky or a PHP git hook library) to enforce the format.

Common Misconception

Why It Matters

Common Mistakes

• Inconsistent type prefixes across the team — some use 'feature:', others 'feat:', others nothing.
• Vague commit bodies: 'fix: bug' — the body should explain what was broken and how it was fixed.
• Not using BREAKING CHANGE footer for breaking API changes — automated tooling cannot detect them.
• Over-strict enforcement driving developers to make huge commits to avoid multiple messages.

Code Examples

# Non-conventional commits — no structure:
git log:
  'fixed stuff'
  'wip'
  'FINAL'
  'changes'
  'more changes'

# Conventional commits:
  'feat(auth): add OAuth2 Google login'
  'fix(session): regenerate ID after privilege change'
  'docs: add deployment runbook'
  'feat!: rename user_name to username (BREAKING CHANGE)'

# Format: <type>(<scope>): <short description>

git commit -m 'feat(auth): add OAuth2 login via GitHub'
git commit -m 'fix(cart): prevent duplicate line items on concurrent add'
git commit -m 'refactor(payment): extract StripeGateway to adapter class'
git commit -m 'perf(query): add covering index on orders.user_id'
git commit -m 'docs(api): document /orders endpoint rate limits'
git commit -m 'test(checkout): add integration test for card decline flow'
git commit -m 'chore(deps): bump phpunit to 11.1'

# BREAKING CHANGE — add ! and footer:
git commit -m 'feat(api)!: rename /users to /members

BREAKING CHANGE: clients must update all /users references to /members'

References

• ↗ https://www.conventionalcommits.org/en/v1.0.0/

Tags

Related Terms