engineering-handbook/pull-requests.md

# Pull Requests

## Scope

Each PR should represent a single logical change. If you find yourself writing "and" in the title, consider splitting it into separate PRs.

| Good scope | Too broad |
|---|---|
| Add receipt parser Lambda | Add receipt parser and refactor auth middleware |
| Fix timeout in payment processor | Fix timeout and update dependencies |
| Update Lambda runtime to Python 3.12 | Update runtime and add new endpoint |

## Title

- Use the Conventional Commit format with a required Jira key suffix: `type(scope): description (KEY-123)`
- `scope` is optional; omit it when the change is broad or no single scope applies
- Active keys are `DEV`, `PLAT`, and `SEC`
- Keep the full title under 72 characters
- Describe the change, not the ticket

| Good | Bad |
|---|---|
| `feat(parser): add retry logic for transient upstream failures (DEV-42)` | `JIRA-123` |
| `fix(auth): correct null check in session handler (PLAT-7)` | `Bug fix` |
| `build: update Lambda runtime to Python 3.12 (DEV-88)` | `Updates` |

**Exemptions:** Dependabot PRs and permission-controlled emergency reverts are the only PRs that may omit the Jira key suffix.

## Description

Use a structured format with exactly these four sections in this order:

```markdown
## Summary
What changed and why — 1-3 sentences. Explain the motivation, not just the diff.

## Validation
How you verified it works — steps taken, commands run, screenshots if UI.

## Tests
What tests were added, updated, or run. If no automated tests, explain manual testing.

## Notes
Anything reviewers should know — migration steps, deploy order, follow-ups, breaking changes. Use `None.` when this section has nothing to say; do not omit it.
```

The summary should explain **why** the change is needed, not just restate the diff. Reviewers can read the code; they need context.

State verifiable facts about the code. Do not cite the engineering handbook, and do not include AI attribution footers.

## When to Open a PR

- When the work is ready for review, not as a draft for parking incomplete work
- After verifying locally that the change works as expected
- The deploy happens after the PR merges to `main`; see [Deploying](git-workflow.md#deploying)

## Merging

- Squash merge for feature branches with messy interim commits
- Regular merge for branches with clean, meaningful commit history
- Delete the branch after merge