Pull Request Best Practices

Why Are PRs Important?

  • Incredibly valuable feedback mechanism
  • Great opportunity to catch bugs early on
  • Form of documentation and record-keeping
  • Natural forum for discussion

Writing PRs: Always Link Relevant Issue

  • Allows the reviewer to access the story to validate if all requirements/acceptance criteria are being met.
  • If you install the Linkify JIRA Issues Chrome extension and mention the issue in the title, it will auto link back to the JIRA issue

Writing PRs: Include Details in the Decsription

  • Include as many details as possible in the description field, such as setup steps, your thought process, PR dependencies from other repos, edge cases to check, etc...
  • Add a "DO NOT MERGE" label if you need the PR to be reviewed but not merged...otherwise assume it will get merged ASAP

Writing PRs: QA Your Stuff

  • Before submitting the PR, make sure you QA the topic branch locally.
  • For UI-related PRs, this includes testing this like responsiveness
  • As engineers, it is our responsibility to ensure we have properly accounted for as many edge cases as possible.
  • QA should be considered a last line of defense to account for the most obscure of edge cases.

Writing PRs: Screenshots or GIFs for UI PRs

  • For UI related PRs, always include a GIFy or screenshot
  • This makes it easy for the reviewer to know where and what to look for when QAing the PR
  • Allows tech lead & product manager to get a quick glimpse at the feature before it lands in sandbox

Writing PRs: Utilize Assignee Feature

  • Use the "Assignee" section in Github to tag who should take action next
  • For Example:
    • I tag the reviewer as the Assignee
    • Reviewer gives their feedback, removes themselve as Assignee, and tags the writer as the Assignee so they can incorporate any feedback
    • Repeat as needed
  • The "Reviewer" section should always be whatever reviewers should be on the PR

Writing PRs: Include Documentation

  • Always include documentation/comments where appropriate
  • Complex sections of code should always include clarifying comments
  • Any app/library READMEs or scripts should include full setup instructions, command-line task descriptions, and API documentation
  • Always assume the person coming into this code or repo has no idea how it works

Writing PRs: Other Tidbits

  • Give descriptive commit messages and titles
  • Commit messages should be phrased in the form of what the commit does
    • "Changes the button hover color to red"
    • "Adds the DELETE /event endpoint for soft-deleting events"

Reviewing PRs: Read the Code!

  • No matter how small the PR, resist the temptation to simply gloss over it and give it a "LGTM     "
  • Do not assume a PR from a more senior team member is solid and does not require an in-depth review
  • "Your team is only as good as your weakest reviewer" - Joel Kemp

Reviewing PRs: Give Contextual References

  • Where appropriate, give an example code snippet or link a relevant article/tutorial
  • These help provide clarity + encourage the engineer learn and apply the knowledge on their own
  • If possible, try not to solve the problem for them...guide them to discovering a solution

Reviewing PRs: Check for Test Coverage

  • Where appropriate, make sure that the PR has the appropriate amount of test coverage
  • Make sure that the tests are good tests that actually validate whether or not the functionality works + accounts for edge cases
  • Make sure the tests can be run in isolation from one another! The setup/teardown process of one test should not affect the results of other tests

Reviewing PRs: Show Respect

  • Always remember to treat others the way you would want to be treated
  • Try to refrain from using a condescending or confrontational tone
  • Give compliments!

Reviewing PRs: Other Tidbits

  • Review CSS/HTML just as you would JS
  • If you are assigned a reviewer, go ahead and QA the topic branch locally
  • Always be thinking about edge cases when reviewing/QAing
  • Make sure there is proper documentation/comments

Other Resources

Pull Request Best Practices

By Rohit Kalkur

Pull Request Best Practices

Best Practices for Reading/Writing Pull Requests

  • 2,461