update merge queue docs (#26396)

* update merge queue docs

content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/adding-a-pull-request-to-the-merge-queue.md

@@ -1,61 +0,0 @@
----
-title: Adding a pull request to the merge queue
-intro: 'If merge queues are enabled for the repository, you can add your pull requests to the merge queue once all the required checks have passed. {% data variables.product.product_name %} will merge the pull requests for you.'
-versions:
-  fpt: '*'
-  ghec: '*'
-topics:
-  - Pull requests
-shortTitle: Add PR to merge queue
-redirect_from:
-  - /github/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/adding-a-pull-request-to-the-merge-queue
----
-
-{% data reusables.pull_requests.merge-queue-beta %}
-
-## About pull request merge queue
-
-{% data reusables.pull_requests.merge-queue-overview-short %}
-{% data reusables.pull_requests.merge-queue-references %}
-
-## Adding a pull request to the merge queue
-
-{% data reusables.repositories.navigate-to-repo %}
-{% data reusables.repositories.sidebar-pr %}
-1. In the "Pull Requests" list, click the pull request you'd like to add to the merge queue.
-1. Click **Add to merge queue** to add your pull request to the merge queue. This enables the default **Queue and merge in a group** option. Alternatively, you can:
-   - Add your pull request to the front of the queue by selecting the **Add to merge queue** drop down menu, and clicking **Jump the queue** (only available to repository maintainers and administrators).
-   - Directly merge your pull request by selecting the **Add to merge queue** drop down menu, and clicking **Directly merge** (only available to repository administrators).
-   ![Merge queue options](/assets/images/help/pull_requests/merge-queue-options.png)
-
-   {% tip %} 
-
-   **Tip:** The **Add to merge queue** button is only enabled once the pull request meets all the review/approval and status check requirements.
-
-   {% endtip %}
-2. Confirm you want to add the pull request to the merge queue by clicking **Confirm add to merge queue**.
-   {% data variables.product.product_name %} adds the pull request to the merge queue and will merge it for you.
-
-## Viewing the merge queue
-
-You can view the merge queue in various places on {% data variables.product.product_name %}.
-
-   - On the **Branches** page for the repository. We recommend you use this route if you don't have or don't know about a pull request already in the queue, and if you want to see what's in the queue. For more information, see "[Viewing branches in your repository](/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/viewing-branches-in-your-repository)."
-
-  ![View merge queue in Branches page](/assets/images/help/pull_requests/merge-queue-branches-page.png)
-
-- On the **Pull requests** page of your repository, click {% octicon "clock" aria-label="The clock symbol" %}.
-
-  ![View merge queue on Pull requests page](/assets/images/help/pull_requests/clock-icon-in-pull-request-list.png)
-
-- On your pull request, scroll down to the section with the checks, and click **View merge queue**.
-
-  ![View Merge queue button on pull request](/assets/images/help/pull_requests/view-merge-queue-button.png)
-
-The merge queue view shows the pull requests that are currently in the queue, with your pull requests clearly marked.
-
-![Merge queue view](/assets/images/help/pull_requests/merge-queue-view.png)
-
-## Handling pull requests removed from the merge queue
-	
-{% data reusables.pull_requests.merge-queue-reject %}

content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/index.md

@@ -16,7 +16,7 @@ children:
   - /about-pull-request-merges
   - /merging-a-pull-request
   - /automatically-merging-a-pull-request
-  - /adding-a-pull-request-to-the-merge-queue
+  - /merging-a-pull-request-with-a-merge-queue
   - /closing-a-pull-request
   - /reverting-a-pull-request
 shortTitle: Incorporate changes

content/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request-with-a-merge-queue.md

@@ -0,0 +1,74 @@
+---
+title: Merging a pull request with a merge queue
+intro: 'If a merge queue is required by the branch protection setting for the branch, you can add your pull requests to a merge queue and {% data variables.product.product_name %} will merge the pull requests for you once all required checks have passed.'
+versions:
+  fpt: '*'
+  ghec: '*'
+topics:
+  - Pull requests
+shortTitle: Merge PR with merge queue
+redirect_from:
+  - /pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/adding-a-pull-request-to-the-merge-queue
+---
+
+{% data reusables.pull_requests.merge-queue-beta %}
+
+## About merge queues
+
+{% data reusables.pull_requests.merge-queue-overview %}
+{% data reusables.pull_requests.merge-queue-references %}
+
+## Adding a pull request to a merge queue
+
+{% data reusables.repositories.navigate-to-repo %}
+{% data reusables.repositories.sidebar-pr %}
+
+1. In the "Pull Requests" list, click the pull request you would like to add to a merge queue.
+
+1. Click **Merge when ready** to add the pull request to the merge queue. Alternatively, if you are an administrator, you can:
+   -  Directly merge the pull request by checking **Merge without waiting for requirements to be met (administrators only)**, if allowed by branch protection settings, and follow the standard flow.
+   ![Merge queue options](/assets/images/help/pull_requests/merge-queue-options.png)
+
+  {% tip %}
+
+  **Tip:** You can click  **Merge when ready** whenever you're ready to merge your proposed changes. {% data variables.product.product_name %} will automatically add the pull request to the merge queue once required approval and status checks conditions are met.
+
+  {% endtip %}
+
+1. Confirm you want to add the pull request to the merge queue by clicking  **Confirm merge when ready**.
+
+## Removing a pull request from a merge queue
+
+{% data reusables.repositories.navigate-to-repo %}
+{% data reusables.repositories.sidebar-pr %}
+
+1. In the "Pull Requests" list, click the pull request you would like to remove from a merge queue.
+
+1. To remove the pull request from the queue, click **Remove from queue**.
+  ![Remove pull request from queue](/assets/images/help/pull_requests/remove-from-queue-button.png)
+
+Alternatively, you can navigate to the merge queue page for the base branch, click **...** next to the pull request you want to remove, and select **Remove from queue**. For information on how to get to the merge queue page for the base branch, see the section below.
+
+## Viewing merge queues
+
+You can view the merge queue for a base branch in various places on {% data variables.product.product_name %}.
+
+- On the **Branches** page for the repository. We recommend you use this route if you don't have or don't know about a pull request already in a queue, and if you want to see what's in that queue. For more information, see "[Viewing branches in your repository](/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/viewing-branches-in-your-repository)."
+
+  ![View merge queue in Branches page](/assets/images/help/pull_requests/merge-queue-branches-page.png)
+
+- On the **Pull requests** page of your repository, click {% octicon "clock" aria-label="The clock symbol" %} next to any pull request in the merge queue.
+
+  ![View merge queue on Pull requests page](/assets/images/help/pull_requests/clock-icon-in-pull-request-list.png)
+
+- On the pull request page when merge queue is required for merging, scroll to the bottom of the timeline and click **the merge queue** link.
+
+  ![Merge queue link on pull request](/assets/images/help/pull_requests/merge-queue-link.png)
+
+- The merge queue view shows the pull requests that are currently in the queue, with your pull requests clearly marked.
+
+  ![Merge queue view](/assets/images/help/pull_requests/merge-queue-view.png)
+
+## Handling pull requests removed from the merge queue
+
+{% data reusables.pull_requests.merge-queue-reject %}

content/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/index.md

@@ -15,7 +15,7 @@ children:
   - /about-merge-methods-on-github
   - /configuring-commit-squashing-for-pull-requests
   - /configuring-commit-rebasing-for-pull-requests
-  - /using-a-merge-queue
+  - /managing-a-merge-queue
   - /managing-suggestions-to-update-pull-request-branches
   - /managing-auto-merge-for-pull-requests-in-your-repository
   - /managing-the-automatic-deletion-of-branches

content/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue.md

@@ -0,0 +1,58 @@
+---
+title: Managing a merge queue
+intro: You can increase development velocity with a merge queue for pull requests in your repository.
+versions:
+  fpt: '*'
+  ghec: '*'
+permissions: People with admin permissions can manage merge queues for pull requests targeting selected branches of a repository.
+topics:
+  - Repositories
+  - Pull requests
+shortTitle: Managing merge queue
+redirect_from:
+  - /repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/using-a-merge-queue
+---
+
+{% data reusables.pull_requests.merge-queue-beta %}
+
+## About merge queues
+
+{% data reusables.pull_requests.merge-queue-overview %}
+
+The merge queue creates temporary branches with a special prefix to validate pull request changes. The changes in the pull request are then grouped with the latest version of the `base_branch` as well as changes ahead of it in the queue. {% data variables.product.product_name %} will merge all these changes into `base_branch` once the checks required by the branch protections of `base_branch` pass. 
+
+You may need to update your Continuous Integration (CI) configuration to trigger builds on branch names that begin with the special prefix `gh-readonly-queue/{base_branch}` after the group is created.
+
+For example, with {% data variables.product.prodname_actions %}, a workflow with the following trigger will run each time a pull request that targets the base branch `main` is queued to merge.
+
+```yaml
+on:
+  push:
+    branches:
+    - gh-readonly-queue/main/**
+```
+
+{% data reusables.pull_requests.merge-queue-merging-method %}
+
+For information about merge methods, see "[About pull request merges](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges)."
+
+{% note %}
+
+**Note:**
+
+* A merge queue cannot be enabled with branch protection rules that use wildcard characters (`*`) in the branch name pattern.
+
+{% endnote %}
+
+{% data reusables.pull_requests.merge-queue-reject %}
+
+## Managing a merge queue
+
+Repository administrators can require a merge by enabling the branch protection setting "Require merge queue" in the protection rules for the base branch.
+
+For information about how to enable the merge queue protection setting, see "[Managing a branch protection rule](/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/managing-a-branch-protection-rule#creating-a-branch-protection-rule)."
+
+## Further reading
+
+* "[Merging a pull request with a merge queue](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request-with-a-merge-queue)"
+* "[About protected branches](/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/about-protected-branches)"

content/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/using-a-merge-queue.md

@@ -1,55 +0,0 @@
----
-title: Using a merge queue
-intro: You can increase development velocity by enabling merge queues for pull requests in your repository.
-versions:
-  fpt: '*'
-  ghec: '*'
-permissions: People with admin permissions can configure merge queues for pull requests targeting selected branches of a repository.
-topics:
-  - Repositories
-  - Pull requests
-shortTitle: Use merge queue
----
-
-{% data reusables.pull_requests.merge-queue-beta %}
-
-## About pull request merge queue
-
-{% data reusables.pull_requests.merge-queue-overview %}
-
-The merge queue creates temporary preparatory branches to validate pull requests against the latest version of the base branch. To ensure that {% data variables.product.prodname_dotcom %} validates these preparatory branches, you may need to update your CI configuration to trigger builds on branch names starting with `gh-readonly-queue/{base_branch}`. 
-
-For example, with {% data variables.product.prodname_actions %}, adding the following trigger to a workflow will cause the workflow to run when any push is made to a merge queue preparatory branch that targets `main`.
-
-```
-on:
-  push:
-    branches:
-    - main
-    - gh-readonly-queue/main/**
-```
-
-{% data reusables.pull_requests.merge-queue-merging-method %}
-
-For information about merge methods, see "[About pull request merges](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges)." For information about the "Require linear history" branch protection setting, see "[About protected branches](/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/about-protected-branches#require-linear-history)."
-
-{% note %} 
-
-**Note:** During the beta, there are some limitations when using the merge queue:
-
-* The merge queue cannot be enabled on branch protection rules using wildcards (`*`) in the name.
-* There is no support for squash merge commits. (Only merge commits and "rebase and merge" commits are supported.)
-
-{% endnote %}
-
-{% data reusables.pull_requests.merge-queue-reject %}
-## Managing pull request merge queue
-
-Repository administrators can configure merge queues for pull requests targeting selected branches of a repository. The requirement to use a merge queue is a branch protection setting called "Require merge queue" that can be enabled in branch protection rules.
-
-For information about how to enable the merge queue protection setting, see "[Managing a branch protection rule](/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/managing-a-branch-protection-rule#creating-a-branch-protection-rule)."
-
-## Further reading
-
-- "[Adding a pull request to the merge queue](/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/adding-a-pull-request-to-the-merge-queue)"
-- "[About protected branches](/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/about-protected-branches)"

data/reusables/pull_requests/merge-queue-merging-method.md

@@ -1,2 +1,3 @@
-Once CI checks pass, {% data variables.product.product_name %} merges the pull request by fast-forwarding the default branch. The merge queue will use merge commits if the "Require linear history" branch protection setting is turned off, and the "Rebase and merge" method otherwise. 
- 
+{% data variables.product.product_name %} merges the pull request according to the merge strategy configured in the branch protection once all required CI checks pass.
+
+![Merge queue merging method](/assets/images/help/pull_requests/merge-queue-merging-method.png)

data/reusables/pull_requests/merge-queue-overview-short.md

@@ -1,3 +0,0 @@
-If repository administrators enable merge queues for pull requests targeting selected branches within a repository, contributors to these branches can add their pull requests to a merge queue once the required checks have passed. 
-
-{% data variables.product.product_name %} will process the merge queue, and will merge the pull requests on your behalf if you're a contributor, by fast-forwarding the default branch.

data/reusables/pull_requests/merge-queue-overview.md

@@ -1,5 +1,5 @@
-Merge queues for pull requests can increase the rate at which pull requests are merged into a busy default branch, whilst ensuring that CI checks pass.
+A merge queue can increase the rate at which pull requests are merged into a busy target branch while ensuring that all required branch protection checks pass.
 
-Merge queues use {% data variables.product.prodname_actions %}. For more information about actions, see "[{% data variables.product.prodname_actions %}](/actions/)."
+Once a pull request has passed all of the required branch protection checks, a user with write access to the repository can add that pull request to a merge queue.
 
-Once a pull request has passed any required checks and approvals, a contributor with write access can add the pull request to the merge queue. The queue then creates a temporary branch with that pull request and any pull requests ahead of it in the queue, and triggers any required continuous integration (CI) checks.
+A merge queue may use {% data variables.product.prodname_actions %}. For more information, see "[{% data variables.product.prodname_actions %}](/actions/)."

data/reusables/pull_requests/merge-queue-references.md

@@ -1,2 +1,2 @@
 
-For more information about merge queues, see "[Using a merge queue](/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/using-a-merge-queue)."
+For information about merge queue, see "[Managing a merge queue](/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue)."

data/reusables/pull_requests/merge-queue-reject.md

@@ -1,2 +1,2 @@
 
-If there are failed status checks or conflicts with the base branch, {% data variables.product.product_name %} will remove the pull request from the queue. The pull request timeline will display the reason why the pull request has been removed from the queue.
+After grouping a pull request with the latest version of the target branch and changes ahead of it in the queue, if there are failed required status checks or conflicts with the base branch, {% data variables.product.product_name %} will remove the pull request from the queue. The pull request timeline will display the reason why the pull request was removed from the queue.

lib/search/popular-pages.json

@@ -627,7 +627,7 @@
 {"path_article": "repositories/viewing-activity-and-data-for-your-repository/viewing-a-summary-of-repository-activity", "path_count": 2701}
 {"path_article": "issues/using-labels-and-milestones-to-track-work/creating-and-editing-milestones-for-issues-and-pull-requests", "path_count": 2699}
 {"path_article": "actions/managing-workflow-runs/skipping-workflow-runs", "path_count": 2694}
-{"path_article": "repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/using-a-merge-queue", "path_count": 2677}
+{"path_article": "repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue", "path_count": 2677}
 {"path_article": "code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/managing-code-scanning-alerts-for-your-repository", "path_count": 2664}
 {"path_article": "developers/apps/building-oauth-apps", "path_count": 2649}
 {"path_article": "developers/apps/building-github-apps/refreshing-user-to-server-access-tokens", "path_count": 2646}