engineering-handbook/commit-messages.md

# Commit Messages

> Adapted from [commit-messages-guide](https://github.com/RomuloOliveira/commit-messages-guide) by Romulo Oliveira, licensed under [CC-BY-4.0](https://creativecommons.org/licenses/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: PROJ-123, #123
```

## Referencing issues

Use the `Refs:` trailer to point at the work this commit relates to:

- **Jira key** (`PROJ-123`) when the work tracks a Jira issue. The GitHub for Jira app reads the key and threads the commit into the issue's development panel. See [git-workflow.md](git-workflow.md#linking-to-jira).
- **GitHub issue** (`#123`) when the work tracks a GitHub issue in the same repo.

List both when both apply: `Refs: PROJ-123, #123`. The key only needs to appear once in the branch, PR title, or any commit for the link to form, but including it in the trailer keeps the reference attached to the individual change.

## 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: PROJ-123
```