In this guide
A good pull request helps the reviewer understand why you made the change, what you did, and how to verify it. Suppose a checkout client can create a second order when the first response times out and the client retries. You could title your PR Prevent duplicate orders when checkout retries. It names the outcome and the situation that triggers the problem.
Give the reviewer enough context
Use one sentence to describe the behavior that prompted the PR. Then describe the decision in terms that make sense to someone opening the diff for the first time. In this example, the server already supports idempotency keys, and the client now reuses the key when it retries the same checkout attempt. That lets the server recognize the repeated request and return the original result. Stripe’s API documentation shows how one real API uses keys to recognize retries. Stripe API documentation
Link a relevant issue if the reviewer might need the background. GitHub’s guidance also asks authors to spell out the purpose of the PR and the kind of feedback they’re looking for. GitHub Blog
A complete pull request description
Context. If the server creates an order but the response times out, the checkout client may retry the request.
Change. This PR reuses the same idempotency key when the client retries a checkout attempt.
The server then returns the original order.
Testing. I added a regression test that simulates a timeout after the server creates the order.
The retry returns the same order ID.
Review focus. Could you check how we handle a retry after the checkout page reloads?
I added a regression test tells the reader what coverage came with the change. If you also tested it manually, name the environment and what you observed. For instance, I verified in staging that the retry returned the original order ID gives the reviewer an outcome they can check. If a scenario is still being tested, mention what’s pending and who will follow up.
Ask for code review with a specific focus
Could you review this PR? is a general request. Add the part where you want another pair of eyes with Could you check whether the retry flow handles a page reload? If there’s a deadline, include a time such as by 16:00 UTC.
When you ask in Slack or your team chat, share the link and a one-sentence summary. That gives your teammate enough context to prioritize the review. How thoughtbot requests PR reviews in Slack
Practice writing your next PR
Pick one small change you made this week. Start the title with Fix, Add, or Prevent and name the behavior that changes. Write one sentence of context, one about how you verified the change, and one question that points the reviewer to a specific part of the diff.
Read the description aloud. It can also help you explain your PR in a daily stand-up.