Script Valley
Reading Other People's Code
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

Pull request description structure diagram

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.

Up next

How to refactor code you didn't write without breaking it

Sign in to track progress

How to write a good pull request description for unfamiliar code โ€” Contributing to an Existing Codebase โ€” Reading Other People's Code โ€” Script Valley โ€” Script Valley