Contributing to an Existing CodebaseLesson 5.4
How to write a good pull request description for unfamiliar code
PR description structure, explaining why not what, blast radius documentation, testing evidence, migration notes, reviewer guidance, screenshots for UI changes
The PR Description Is Code Review Prep
A good PR description doesn't describe the diff — the reviewer can read the diff. It explains the reasoning, context, and risk that the diff alone doesn't show.
PR Description Template
## Why
The checkout flow was crashing for users with gift card balances because
`calculateTotal()` returned negative values when gift cards exceeded order total.
Fixes #841.
## What Changed
- Added `Math.max(0, ...)` guard in `calculateTotal()` to floor at zero
- Updated `applyGiftCard()` to return the remaining balance for use in the UI
- Added validation in the gift card input component
## Blast Radius
- `calculateTotal` is called in 3 places: checkout, cart summary, order preview
- All three are updated and tested
- No database changes
## Testing Evidence
- Added 4 unit tests covering: normal case, exact balance, excess balance, zero balance
- Manually tested with test gift card codes in staging
- Ran full checkout flow: passes
## Migration Notes
No migration required. No breaking API changes.The Why section is the most important. If the reviewer understands the problem, they can evaluate whether your solution is correct. Without it, they're reviewing in the dark.
