Rewrites the "Best practices for pull requests" article to center Bui…

…lder jobs to be done (#53453)

content/pull-requests/collaborating-with-pull-requests/getting-started/helping-others-review-your-changes.md

@@ -0,0 +1,82 @@
+---
+title: Helping others review your changes
+intro: 'You can use pull requests to provide clear context for your changes and keep your team informed, improving collaboration and the quality of reviews.'
+redirect_from:
+  - /pull-requests/collaborating-with-pull-requests/getting-started/best-practices-for-pull-requests
+versions:
+  fpt: '*'
+  ghes: '*'
+  ghec: '*'
+topics:
+  - Pull requests
+shortTitle: Help others review your changes
+---
+
+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 "[AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/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?{% ifversion copilot %} Additionally, you can use {% data variables.product.prodname_copilot %} to generate a summary of your pull request. See "[Use {% data variables.product.prodname_copilot %} to generate pull request summaries](#use-github-copilot-to-generate-pull-request-summaries)," later in this article.{% endif %}
+
+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.
+
+{% ifversion copilot %}
+
+### Use {% data variables.product.prodname_copilot %} to generate pull request summaries
+
+> [!NOTE] {% data reusables.copilot.copilot-requires-subscription %}
+
+You can use {% data variables.product.prodname_copilot_short %} to generate a summary of a pull request on {% data variables.product.github %}. You can use the summary to help reviewers understand your changes.
+
+1. On {% data variables.product.github %}, create a pull request or navigate to an existing pull request.
+
+   > [!NOTE] {% data variables.product.prodname_copilot %} does not take into account any existing content in the pull request description, so it is best to start with a blank description.
+
+1. Navigate to the text field where you want to add the pull request summary.
+
+   * If you're creating a new pull request, use the "Add a description" field.
+   * If you're adding a description to an existing pull request, edit the opening comment.
+   * If you're adding a summary as a comment, navigate to the "Add a comment" section at the bottom of the pull request page.
+
+1. In the header of the text field, select {% octicon "copilot" aria-label="Copilot actions" %}, then click **Summary**.
+
+   ![Screenshot of the form for creating a pull request. A Copilot icon is highlighted, and a box appears with the "Summary" command.](/assets/images/help/copilot/copilot-description-suggestion.png)
+
+1. Wait for {% data variables.product.prodname_copilot %} to produce the summary, then check over the results carefully.
+1. Add any additional context that will help people viewing your pull request.
+1. When you're happy with the description, click **Create pull request** on a new pull request, or **Update comment** if you're editing an existing description.
+
+{% endif %}
+
+### 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-LINK` in your description to automatically link and close the issue when the pull request is merged.
+* Use {% data variables.product.prodname_projects_v2 %} to track your work and link to the project from your pull request, making progress easy to track in one place. See "[AUTOTITLE](/issues/planning-and-tracking-with-projects/learning-about-projects/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 "[AUTOTITLE](/issues/using-labels-and-milestones-to-track-work/managing-labels)."

content/pull-requests/collaborating-with-pull-requests/getting-started/index.md

@@ -17,6 +17,6 @@ topics:
   - Fundamentals
 children:
   - /about-collaborative-development-models
-  - /best-practices-for-pull-requests
+  - /helping-others-review-your-changes
+  - /managing-and-standardizing-pull-requests
 ---
-

content/pull-requests/collaborating-with-pull-requests/getting-started/best-practices-for-pull-requests.md → content/pull-requests/collaborating-with-pull-requests/getting-started/managing-and-standardizing-pull-requests.md

@@ -1,72 +1,46 @@
 ---
-title: Best practices for pull requests
-intro: 'You can follow best practices to improve the consistency and quality of pull requests and pull request reviews.'
+title: Managing and standardizing pull requests
+intro: 'Use these steps to manage and standardize the pull requests that contributors create in your repository.'
 versions:
   fpt: '*'
   ghes: '*'
   ghec: '*'
 topics:
   - Pull requests
-shortTitle: Best practices
+shortTitle: Manage and standardize pull requests
 ---
 
-## Best practices for creating pull requests
+If you are a repository maintainer, there are several ways that you can manage and standardize the pull requests that contributors create in your repository. These steps can help you ensure that pull requests are reviewed by the right people, and that they meet your repository's standards.
 
-When creating a pull request, follow a few best practices for a smoother review process. For information on creating a pull request, see "[AUTOTITLE](/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/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
+## Using 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 "[AUTOTITLE](/communities/using-templates-to-encourage-useful-issues-and-pull-requests/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 "[AUTOTITLE](/get-started/writing-on-github/working-with-advanced-formatting/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 "[AUTOTITLE](/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue)."
 
-### Define code owners
+## Defining 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 "[AUTOTITLE](/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners)."
 
-### Use protected branches
+## Using 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 "[AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches)."
 
 {% ifversion push-rulesets %}
 
-### Use push rulesets
+## Using push rulesets
 
 {% data reusables.repositories.push-rulesets-overview %}
 
 For more information, see "[AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets#push-rulesets)."
 
 {% endif %}
 
-### Use automated tools to review code styling
+## Using 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.
 

data/reusables/repositories/push-rulesets-overview.md

@@ -11,6 +11,6 @@ Push rulesets allow you to:
 * **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
+### About push rulesets for forked repositories
 
 {% data reusables.repositories.rulesets-push-rulesets-fork-network-information %}