Refactor pull request concepts around developer jobs-to-be-done (#62071)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Vanessa <vgrl@github.com>
Co-authored-by: Siara <108543037+SiaraMist@users.noreply.github.com>
Copilot-Session: fc48eebe-a846-4e0d-a78a-359e3db86192

Author: 5 people

content/index.md

@@ -7,7 +7,7 @@ featuredLinks:
     - /repositories/creating-and-managing-repositories
     - /get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax
   popular:
-    - /pull-requests/concepts/about-pull-requests
+    - /pull-requests/reference/pull-requests
     - /authentication
     - /copilot/how-tos/get-code-suggestions/get-ide-code-suggestions
     - /get-started/git-basics/managing-remote-repositories
@@ -84,7 +84,6 @@ children:
   - desktop
   - early-access
   - support
-
   - contributing
   - github-models
   - nonprofit
@@ -179,21 +178,22 @@ externalProducts:
   electron:
     id: electron
     name: Electron
-    href: 'https://electronjs.org/docs/latest'
+    href: https://electronjs.org/docs/latest
     external: true
   codeql:
     id: codeql
     name: CodeQL query writing
-    href: 'https://codeql.github.com/docs'
+    href: https://codeql.github.com/docs
     external: true
   npm:
     id: npm
     name: npm
-    href: 'https://docs.npmjs.com/'
+    href: https://docs.npmjs.com/
     external: true
   gh-wa:
     id: gh-wa
     name: GitHub Well-Architected
-    href: 'https://wellarchitected.github.com/'
+    href: https://wellarchitected.github.com/
     external: true
 ---
+

content/pull-requests/concepts/about-pull-request-reviews.md

@@ -0,0 +1,66 @@
+---
+title: Deploying code
+shortTitle: Deploy code
+intro: 'Validate pre-deployment checks, choose merge strategies, and manage branches effectively when deploying code.'
+versions:
+  fpt: '*'
+  ghes: '*'
+  ghec: '*'
+contentType: concepts
+---
+
+The final step for a pull request is to get finished work into the deployment branch. This usually means merging your changes into the release or main branch. Before that happens, you will need to confirm that the change meets the project's requirements.
+
+## Validating pre-deployment checks
+
+Before you merge, you will confirm that the change is safe to deploy. **Status checks** show whether commits meet the conditions set for the repository, such as continuous integration builds, tests, code scanning, or deployment checks. They help you and reviewers understand whether a pull request is ready to merge. 
+
+Repositories often require certain conditions before a pull request can merge, including:
+
+* Required status checks that must pass, such as application health and readiness checks run by your deployment pipeline.
+* Required reviews or code owner approvals.
+* Merge conflicts must be resolved.
+
+Protected branches enforce these requirements so deployment branches stay stable. 
+
+Not all checks are the same. Rich checks created by products like {% data variables.product.prodname_actions %} can report detailed logs and annotations, while simpler commit statuses can be posted by a variety of connected systems. Understanding these helps you interpret why a pull request is or isn't ready. 
+
+## Merging code into the release or main branch
+
+When the requirements are met, you merge the pull request to bring its commits into the base branch. You can also automate merging so a pull request merges as soon as its requirements are met. Pull requests offer different merge strategies depending on how you want the repository history to look:
+
+* **Merge commit** preserves every commit from the pull request branch and adds an explicit merge point.
+* **Squash and merge** combines all commits into a single commit for a concise history.
+* **Rebase and merge** adds each commit onto the base branch for a linear history without a merge commit.
+
+The best strategy depends on how much detail your team wants to preserve.
+
+## Enforcing requirements at scale
+
+As merging gets busier, teams add controls to keep merges safe and predictable:
+
+* **Rulesets and branch protections** can require an up-to-date branch, signed commits, linear history, or specific status checks before merging. 
+* A **merge queue** lets a high-traffic protected branch accept many pull requests without breaking. It tests each one against the latest version of the base branch and merges them in order once checks pass. When a branch uses a merge queue, the available merge options differ from a standard merge. 
+
+> [!NOTE]
+> {% data reusables.gated-features.merge-queue %}
+
+## Connecting merges to deployment
+
+Merging is often the trigger that ships code. {% data variables.product.prodname_actions %} can run deployment workflows when a pull request merges into a release or main branch. **Deployment environments** add another layer of pre-deployment safety: you can require specific reviewers, wait timers, or branch restrictions before a deployment proceeds, and these are surfaced alongside your other checks. 
+
+## Recovering after a merge
+
+Even with checks in place, some merges need to be undone. You can revert a merged pull request to create a new pull request that reverses the changes. Be aware, a pull request can be marked as merged *indirectly* on rare occasions, if its commits reach the base branch through another path. This can bypass the protections on that specific pull request. See [AUTOTITLE](/pull-requests/how-tos/merge-and-close-pull-requests/reverting-a-pull-request) and [AUTOTITLE](/pull-requests/reference/pull-request-merges#indirect-merges).
+
+## Closing pull requests that won't be merged
+
+Not every pull request should merge. If a change is no longer needed or is superseded by other work, you can close the pull request without merging it. Closing keeps the discussion and history for reference while signaling that the change will not move forward.
+
+After a pull request is merged or closed, its head branch is often no longer needed. Deleting unused branches keeps the repository easier to navigate.
+
+## Further reading
+
+* [AUTOTITLE](/pull-requests/how-tos/merge-and-close-pull-requests/merging-a-pull-request)
+* [AUTOTITLE](/pull-requests/reference/status-checks)
+* [AUTOTITLE](/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments)

content/pull-requests/concepts/about-status-checks.md

@@ -0,0 +1,48 @@
+---
+title: Giving reviews
+shortTitle: Give reviews
+intro: 'Provide feedback on pull requests by commenting on changes, suggesting edits, and approving or requesting updates before merging code.'
+versions:
+  fpt: '*'
+  ghes: '*'
+  ghec: '*'
+contentType: concepts
+---
+
+Reviewing pull requests is one of the main ways people collaborate on {% data variables.product.github %}. When you review a peer's work, you help catch issues early, share knowledge, and decide whether a change is ready to merge. 
+
+## Commenting on changes
+
+Anyone with read access can review and comment on proposed changes. As a reviewer, you can:
+
+* Leave general feedback on the overall pull request.
+* Comment on specific lines to ask questions or explain concerns.
+* Suggest exact changes that the author can apply with a single click.
+
+Review conversations appear in the pull request timeline so the whole team can follow the discussion and track decisions. 
+
+## Requesting changes and approving
+
+When you finish a review, you submit it with a decision that tells the author what to do next:
+
+* **Comment** leaves general feedback without explicitly approving or requesting changes.
+* **Approve** signals that the changes are ready to merge.
+* **Request changes** flags feedback that the author should address before the pull request merges.
+
+## Reviewing changes with more depth
+
+Thorough reviews go beyond reading the diff top to bottom. {% data variables.product.github %} gives you tools to review large or complex changes with precision:
+
+* **Review one file at a time**, mark each file as **Viewed** to collapse it, and use the progress bar to track how much of the pull request you've covered.
+* **Assess security and dependencies.** Dependency review shows how a pull request changes dependencies and whether it introduces known vulnerabilities, and code scanning surfaces alerts on the proposed changes.
+{% ifversion fpt or ghec %}
+* **Automate reviews with {% data variables.product.prodname_copilot_short %}.** {% data variables.product.prodname_copilot_short %} can perform automated code reviews on a pull request, comment on specific lines, and suggest changes, helping you catch common issues before a human reviewer looks at the code.
+{% endif %}
+
+## Further reading
+
+* [AUTOTITLE](/pull-requests/get-started/reviewing-pull-requests-quickstart)
+* [AUTOTITLE](/pull-requests/how-tos/review-pull-requests/reviewing-dependency-changes-in-a-pull-request) 
+{% ifversion fpt or ghec %}
+* [AUTOTITLE](/copilot/concepts/agents/code-review).
+{% endif %}