Commit Message Convention

Problem

Commit messages are cryptic and inconsistent: “fix stuff”, “updates”, “wip” provide no context about what changed or why. Developers waste time digging through code diffs to understand commit history, and generating changelogs becomes a manual, error-prone process of interpreting vague commit messages.

Solution

Adopt a structured format like Conventional Commits that prefixes messages with types (feat, fix, docs) and optional scopes. This creates machine-readable history that enables automated changelog generation and helps developers quickly understand the nature of each change.

Example

This example demonstrates the Conventional Commits format with type prefixes and scope identifiers to create standardized, machine-readable commit messages.

# Feature: New functionality added to the codebase
feat(auth): add password reset flow

# Bug fix: Corrects existing functionality
fix(cart): prevent duplicate items

# Documentation: Changes to documentation only, no code changes
docs(api): update authentication guide

# Refactor: Code restructuring without changing functionality
refactor(user): simplify profile validation

Benefits

• Creates clear, searchable commit history that’s easy to understand.
• Enables automated changelog and release note generation.
• Makes it obvious whether a change is a feature, fix, or breaking change.
• Helps with semantic versioning by identifying the type of changes.
• Improves code review by providing context at a glance.

Tradeoffs

• Requires team discipline and training to follow conventions consistently.
• Can feel restrictive or overly formal for small projects or personal repos.
• May slow down commits initially as developers learn the format.
• Automated tools may enforce conventions that feel pedantic.
• Some nuanced changes don’t fit neatly into predefined categories.