Best practices for pull requests

You can follow best practices to improve the consistency and quality of pull requests and pull request reviews.

In this article

Best practices for creating pull requests

When creating a pull request, follow a few best practices for a smoother review process. 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.

Best practices for managing pull requests

If you are a repository maintainer, take these steps to manage and standardize the pull requests that contributors create in your repository.

Use pull request templates

Pull request templates let you customize and standardize the information you'd like to be included when someone creates a pull request in your repository. When you add a pull request template to your repository, project contributors will automatically see the template's contents in the pull request body. For more information, see "Creating a pull request template for your repository."

You can use pull request templates to standardize the review process for your repository. For example, you can include a list of tasks that you would like authors to complete before merging their pull requests, by adding a task list to the template. For more information, see "About task lists."

You can request that contributors include an issue reference in their pull request body, so that merging the pull request will automatically close the issue. For more information, see "Linking a pull request to an issue."

Define code owners

You may want to make sure that specific individuals always review changes to certain code or files in your repository. For example, you may want a technical writer on your team to always review changes in the docs directory.

You can define individuals or teams that you consider responsible for code or files in a repository to be code owners. Code owners will automatically be requested for review when someone opens a pull request that modifies the files that they own. You can define code owners for specific types of files or directories, as well as for different branches in a repository. For more information, see "About code owners."

Use protected branches

You can use protected branches to prevent pull requests from being merged into important branches, such as main, until certain conditions are met. For example, you can require passing CI tests or an approving review. For more information, see "About protected branches."

Use push rulesets

Note

Push rulesets are in beta and subject to change.

With push rulesets, you can block pushes to a private or internal repository and that repository's entire fork network based on file extensions, file path lengths, file and folder paths, and file sizes.

Push rules do not require any branch targeting because they apply to every push to the repository.

Push rulesets allow you to:

  • Restrict file paths: Prevent commits that include changes in specified file paths from being pushed.

    You can use fnmatch syntax for this. For example, a restriction targeting test/demo/**/* prevents any pushes to files or folders in the test/demo/ directory. A restriction targeting test/docs/pushrules.md prevents pushes specifically to the pushrules.md file in the test/docs/ directory. For more information, see "Creating rulesets for a repository."

  • Restrict file path length: Prevent commits that include file paths that exceed a specified character limit from being pushed.

  • Restrict file extensions: Prevent commits that include files with specified file extensions from being pushed.

  • Restrict file size: Prevent commits that exceed a specified file size limit from being pushed.

About push rulesets for forked repositories

Push rules apply to the entire fork network for a repository, ensuring every entry point to the repository is protected. For example, if you fork a repository that has push rulesets enabled, the same push rulesets will also apply to your forked repository.

For a forked repository, the only people who have bypass permissions for a push rule are the people who have bypass permissions in the root repository.

For more information, see "About rulesets."

Use automated tools to review code styling

Use automated tools, such as linters, in your repository's pull requests to maintain consistent styling and make code more understandable. Using automated tools to catch smaller problems like typos or styling leaves more time for reviewers to focus on the substance of a pull request.

For example, you can use GitHub Actions to set up code linters that can run on pull requests as part of your continuous integration (CI) workflow. For more information, see "About continuous integration."