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 at or below 120 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:

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

Merging

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