Write Descriptive Commit Messages

Why this matters

Git history is your codebase's memory. When a production bug appears six months from now, the first tool you reach for is git log and git blame. The commit message is the difference between "fix: prevent duplicate form submission when server responds slowly (closes #847)" — which tells you exactly what, why, and where to look — and "fix bug" — which tells you nothing.

Descriptive commit messages also make git bisect effective. When bisecting a regression across 200 commits, meaningful messages let you skip obviously irrelevant commits and focus on likely candidates. With "update" and "fix" messages, every commit is equally suspect.

This investment is trivial: 30 extra seconds per commit saves hours of debugging later.

The rule

Every commit message should follow the format: type: description that explains the why. Use conventional commit types (feat, fix, refactor, docs, test, chore). The description should explain the motivation, not just restate the diff.

Bad example

fix bug
update code
wip
final fix
please work
changes

Good example

fix: prevent duplicate form submission on slow connections
 
The submit button remained active while waiting for the server
response. On connections >2s latency, users would click again,
creating duplicate records. Disable the button on submit and
show a loading spinner.
 
Closes #847

feat: add CSV export for transaction history
 
Users requested the ability to export transactions for their
accountants. Adds a "Download CSV" button on the transactions
page that exports the current filtered view.
 
Closes #1203

How to detect

Review recent commit messages:

git log --oneline -20

Look for messages that are:

• Under 10 characters
• Generic ("fix", "update", "changes", "wip")
• Missing context about why the change was made

Remediation

1. Adopt a conventional commit format: type(scope): description
2. Use the commit body for additional context (separate from subject with a blank line)
3. Reference issue numbers with Closes #123 or Fixes #456
4. Set up a commit-msg hook with commitlint to enforce the format
5. When reviewing PRs, check commit messages as part of the review — send back vague messages

References

• Conventional Commits
• How to Write a Git Commit Message — Chris Beams
• commitlint