« "Could not find watchman" doesn't actually mean it can't find watchman! | Main | Mapping RGB colors to Philips Hue colors »

What makes a good pull request description?

When you issue a pull request, you're saying, "I changed some code in this repository -- Please pull my change into the project." You should provide a PR description that tells reviewers what they need to know to evaluate your contribution. Better descriptions give better reviews, which end up with a higher-quality codebase.

Most PRs for a front-end web application should include all of these:

  • Purpose: what is this change trying to accomplish? Linking to specifications or tickets is fine, but you must include a one-sentence explanation in the PR description itself.
  • Approach: how does this change accomplish its goal? Explain your approach's architecture at a high level.
  • Worries: Is there anything weird here? Do you have any areas you want help?
  • Before & after screenshots, if the change is visual
  • How to use the feature or exercise the change. Just linking to a ticket with a bug description is not enough; tell the reviewer how they can verify for themselves that the feature is working as planned.

Larger PRs should also include:

  • Did you consider alternative approaches? Why did you go with the approach you chose?
  • How does this relate to other work? Link to other PRs or describe future plans.

Reader Comments

There are no comments for this journal entry. To create a new comment, use the form below.

PostPost a New Comment

Enter your information below to add a new comment.

My response is on my own website »
Author Email (optional):
Author URL (optional):
Some HTML allowed: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <code> <em> <i> <strike> <strong>