When you create a pull request, you’re asking your team to review your changes and provide feedback. This guide provides best practices for creating pull requests that are easy to review and keep your team informed, so that you can improve collaboration and the quality of reviews.
Making your changes easy to review
Clear context in your pull requests helps reviewers quickly see what you’ve changed and why it matters. This makes the review process faster and smoother, with less back-and-forth, and helps your team give better feedback and make confident decisions. For information on creating a pull request, see Creating a pull request.
Write small PRs
Aim to create small, focused pull requests that fulfill a single purpose. Smaller pull requests are easier and faster to review and merge, leave less room to introduce bugs, and provide a clearer history of changes.
Review your own pull request first
Review, build, and test your own pull request before submitting it. This will allow you to catch errors or typos that you may have missed, before others start reviewing.
Provide context and guidance
Write clear titles and descriptions for your pull requests so that reviewers can quickly understand what the pull request does. In the pull request body, include:
- The purpose of the pull request
- An overview of what changed
- Links to any additional context such as tracking issues or previous conversations
To help reviewers, share the type of feedback you need. For example, do you need a quick look or a deeper critique?
If your pull request consists of changes to multiple files, provide guidance to reviewers about the order in which to review the files. Recommend where to start and how to proceed with the review.
Keeping your team informed
Pull requests can do more than just document code changes—they’re also a powerful way to keep your team and manager informed about the status of your work. By making your progress visible in your pull requests, you can reduce the need for separate updates and ensure everyone stays aligned.
Link to related issues or projects
Connect your pull request to relevant issues or project boards to show how your work fits into the larger project.
- Add keywords like
Closes ISSUE-LINKin your description to automatically link and close the issue when the pull request is merged. - Use Projects to track your work and link to the project from your pull request, making progress easy to track in one place. See About Projects.
Highlight the status with labels
Add a status label to your pull request to show whether it’s ready for review, blocked, or in progress. This helps reviewers understand the state of your work at a glance. For more information, see Managing labels.