Stop writing PR descriptions that read like diary entries.
The Problem
Most PR descriptions describe the journey. “First I tried X, then I realized Y, then I refactored Z, and finally I settled on W.” That’s useful for a blog post. It’s terrible for a code review.
The reviewer doesn’t need your autobiography. They need to understand what the code does right now and why.
What to Write Instead
A good PR description answers three questions:
- What does this change? “Replaces the CSV export with a streaming download that handles 100K+ rows without timing out.”
- Why? “Users with large datasets were hitting the 30s gateway timeout.”
- Anything non-obvious? “The chunked response means we can’t set Content-Length upfront, so download progress bars won’t show a percentage.”
That’s it. Three short sections. The reviewer knows exactly what to look for.
But What About the Investigation?
That’s what commit history is for. Your commits capture the evolution: “try batch approach,” “switch to streaming,” “fix memory leak in chunk callback.” Anyone who wants the full story can read the log.
The PR description is the summary. The commits are the chapters. Don’t put the chapters in the summary.
The Litmus Test
Read your PR description six months from now. Will you understand the change in 30 seconds? If you have to re-read your own journey narrative to figure out what the code actually does, you wrote the wrong thing.
Leave a Reply