Skip to content

Instantly share code, notes, and snippets.

@arphox
Last active February 15, 2024 16:35
Show Gist options
  • Save arphox/11cf1e813b67ce01c160752a85daf7cd to your computer and use it in GitHub Desktop.
Save arphox/11cf1e813b67ce01c160752a85daf7cd to your computer and use it in GitHub Desktop.
Pull request best practices

Pull request best practices

A meta-analysis by Károly Ozsvárt

Key takeaways

  • Keep PRs small [1] [2] [3] [4] [5] [7]
  • Break down large pull requests into smaller ones [1] [5]
  • Have a good title [1] [4] [9]
  • Have a good description [1] [4] [9]
  • Reviewing PRs is hard [4] [6]
  • Have good commit messages [4] [7]
  • Make it visual [4] [9]
    • add media if necessary: add screenshots, gifs, videos, explanation drawings, etc.
    • consider before-after "media" [9]
  • Do not squash your commits [7]
  • use a checklist [8]

Too long

  • it seems that it is better to keep your PRs less than 200 lines [3] [5]
  • a good pull request should not have more than 250 lines of code changed [1]
    • PRs with more than 250 lines of changes usually take more than one hour to review [1]
  • Some research suggests that more than 400 lines changed is considered too large for a single review [2]

Content

  • never mix unrelated changes in the same PR [2]
  • Commit message should talk about WHAT changed, and WHY. Not HOW – how is the diff, and you don’t need to repeat it. [4]
  • Be Strict About Temporary Code [6]

Review process

  • Always Provide Constructive Feedback [6]
  • Be Precise About What Needs to be Improved [6]
  • Deploy a test build [7]
  • use templates (commit message, PR) [7]

Links

  1. Anatomy of a perfect pull request
  2. Pull Request Size Matters
  3. Do Larger Pull Requests Receive More Extensive Reviews?
  4. The (written) unwritten guide to pull requests
  5. Optimal pull request size
  6. Best Practices for Reviewing Pull Requests in GitHub
  7. Best practices on doing pull requests
  8. Pull Requests — checklists, metrics and best practices, a definitive guide
  9. Pull request best practices
  10. 10 tips for better Pull Requests by Mark Seemann
@jenol
Copy link

jenol commented Oct 19, 2021

Looks great! Thanks for this.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment