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