engineering-handbook/commit-messages.md

Commit Messages

Adapted from commit-messages-guide by Romulo Oliveira, licensed under CC-BY-4.0.

Rules

Use imperative mood

Write what the commit does, not what you did.

Good	Bad
Add retry logic to payment processor	Added retry logic to payment processor
Fix null check in auth handler	Fixed null check in auth handler
Remove deprecated endpoint	Removing deprecated endpoint

Capitalize the first letter

Good	Bad
Fix null check in auth handler	fix null check in auth handler

Keep the subject line under 50 characters

The subject line is for scanning. Details go in the body.

Wrap the body at 72 characters

If you need to explain more, add a blank line after the subject and write a body wrapped at 72 characters per line.

Explain "why," not "what"

The diff shows what changed. The commit message should explain why.

Good	Bad
Increase timeout to handle slow upstream responses	Change timeout from 30 to 60
Switch to arm64 to reduce Lambda cold start cost	Update architecture setting

No generic messages

These are not acceptable:

• Fix stuff
• Update code
• WIP
• Misc changes
• Address review comments

Every commit should describe a specific change.

No self-referential language

Good	Bad
Fix race condition in queue processor	This commit fixes a race condition
Add input validation for email field	This PR adds validation
Refactor auth middleware for clarity	I refactored the auth middleware

Template

Subject line (50 chars max, imperative, capitalized)

Optional body wrapped at 72 characters. Explain the problem
this commit solves and why this approach was chosen. Mention
side effects or non-obvious consequences.

Refs: #123

Example

Add retry logic for transient upstream failures

The payment processor occasionally returns 503 during
deployments. Without retries, these surface as user-facing
errors. This adds exponential backoff with 3 attempts,
which matches the upstream's documented recovery window.

Refs: #45