Reviewers decide how carefully to read from the description. A blank one says “good luck”; a wall of text says the same thing louder. Three short sections cover almost every PR.
What changed#
One or two sentences, no file list — the diff already shows files. “Adds a queued job that re-sends failed webhook deliveries with backoff” is enough.
Why#
The part that saves the reviewer a Slack message. Link the ticket if there is one, otherwise say what was broken or missing. “Deliveries failed silently when the endpoint returned 5xx, and clients had no way to replay them” is a reason; “requested changes” is not.
How to see it working#
The step everyone skips and the one reviewers want most: the command to run, the page to open, the seed data to create. On a Laravel app that is usually a route to hit, an artisan command, or a test to run:
php artisan test --filter=WebhookRetryTest
Keep it short on purpose#
If the description needs paragraphs, the PR probably needs splitting. Small PRs with three honest sections get read, get real comments, and merge while the context is still warm.
Share this post
Keep reading
Branch Protection Rules That Stick
Three rules cover most of the risk on main: review required, tests green, no force-push. More than that tends to get routed around.
Merging vs Rebasing on a Small Team
Rebase to tidy your own branch, merge to combine into main. One sentence of policy saves a lot of history arguments.
Migrations in Code Review: What to Look For
A merged migration is a fact you cannot edit. The review checklist: reversible down(), safe defaults, indexes, and no data surgery in schema changes.
