docs(merge-queue): choose a merge method per pull request

merge-queue/administration/advanced-settings.mdx

@@ -118,10 +118,10 @@ Choose how your PRs get merged into the target branch. Options are Squash (defau
 
 You can change your merge method at any time:
 
-1. Navigate to the **Merge Queue** tab → **[repository]** → **Settings**
-2. Find the **Merge Method** dropdown
+1. Navigate to the **Merge Queue** tab → **[repository]** → **Settings** → **General**
+2. Find the **Default merge method** dropdown
 3. Select your preferred method: Squash, Merge Commit, or Rebase
-4. The new method will apply to all PRs merged after the change
+4. The new method applies to all PRs merged after the change, except PRs that [chose their own method](#choosing-a-merge-method-per-pull-request) while that setting is on
 
 <Info>
 **Note:** Changing the merge method only affects future merges. PRs already merged will retain their original merge method.
@@ -134,7 +134,40 @@ You can change your merge method at any time:
 * **Repository Size**: Squash merging can help keep repository history more concise
 * **Existing Workflows**: Match your existing GitHub merge button preferences for consistency across your team
 
-The merge method is configured per repository, so different repositories in your organization can use different methods based on their needs.
+The merge method is configured per queue, so different queues in your organization can use different methods based on their needs.
+
+### Choosing a merge method per pull request
+
+By default, every PR merges with the queue's merge method. To let whoever submits a PR choose a different one, turn on **Allow choosing a merge method per pull request**:
+
+1. Navigate to the **Merge Queue** tab → **[repository]** → **Settings** → **General**
+2. Turn on the **Allow choosing a merge method per pull request** toggle
+
+A PR that doesn't choose still merges with the queue's method. Anyone who can submit PRs to the queue can choose.
+
+Choose a method when you submit the PR:
+
+* **Trunk web app:** open the menu beside the submit button and pick one under **Merge method**. **Queue default** uses the queue's method.
+* **Comment:** add `--merge-method=` with `squash`, `rebase`, or `merge` (a merge commit) to `/trunk merge`, for example `/trunk merge --merge-method=rebase`. This also works in a pull request review.
+* **API:** send `mergeMethod` (`squash`, `rebase`, or `mergeCommit`) when you submit or update the PR. See [Merge method](../using-the-queue/api#merge-method).
+
+Submitting with a label or the merge checkbox uses the queue's method. Submitting a PR again without a method, while it waits to enter the queue or after it failed or was cancelled, drops the method it chose before; a PR already in the queue keeps its method. Resubmitting the same commit from the Trunk web app after a failure keeps the method selected.
+
+A chosen method shows on the submit button (for example **Submit to merge queue · Rebase**) and as a **Merge method** badge on the PR's page in Trunk. While the setting is on, Trunk's comment on a PR that is waiting for or in the queue names the method, for example "Trunk will merge this pull request by rebasing its commits (chosen for it)."
+
+When Trunk merges a [stack](../using-the-queue/stacked-pull-requests), every PR it merges together uses the method chosen on the PR you submitted.
+
+If you turn the setting off, every PR merges with the queue's method, including PRs that chose their own. If you turn it back on, those choices apply again.
+
+#### If a merge method is refused
+
+When you submit, Trunk refuses the method and gives the reason (in its reply comment, the web app, or the API response) if:
+
+* The setting is off and the method differs from the PR's current one.
+* The PR is already being merged and you choose a different method.
+* The branch's GitHub rulesets don't allow the method.
+
+If GitHub refuses the method when Trunk merges the PR, Trunk removes the PR from the queue, and its comment on the PR gives GitHub's reason.
 
 ### Custom merge commit titles
 

merge-queue/reference/common-problems.mdx

@@ -29,11 +29,9 @@ og:title: "Trunk Merge Queue FAQ"
     - **Merge Commit** - Preserves all individual commits and creates a merge commit
     - **Rebase** - Replays commits on top of main for a linear history
 
-    The merge method is configured at the repository level in **Merge Queue** → **[your repository]** → **Settings** → **Merge Method**. All PRs merged through the queue will use the selected method.
+    The merge method is configured for each queue in **Merge Queue** → **[your repository]** → **Settings** → **General** → **Default merge method**. PRs merged through the queue use the selected method.
 
-    <Info>
-      **Note:** The merge method applies to the entire repository, not on a per-PR basis. See [Merge Method documentation](/merge-queue/administration/advanced-settings#merge-method) for detailed information on each option and how to configure your preference.
-    </Info>
+    To let a PR use a different method, turn on **Allow choosing a merge method per pull request**; whoever submits the PR can then choose, for example with `/trunk merge --merge-method=rebase`. See [Choosing a merge method per pull request](/merge-queue/administration/advanced-settings#choosing-a-merge-method-per-pull-request), and [Merge method](/merge-queue/administration/advanced-settings#merge-method) for each option.
 
   </Accordion>
 

merge-queue/using-the-queue/api.mdx

@@ -17,6 +17,7 @@ Merge queues are GitHub-only. Install the Trunk GitHub App on the repository, an
 - **Mode**: `queue` mode (**Single** in the app) puts pull requests in one line, each tested on top of the ones ahead of it, several at a time. `graph` mode (**Parallel** in the app) gives unrelated pull requests separate lines, based on the [impacted targets](/merge-queue/optimizations/parallel-queues) CI uploads for each.
 - **Priority**: lower `priorityValue` numbers test first. The names are `urgent` (0), `high` (10), `medium` (100), and `low` (200). Send a number as `priorityValue` or a name as `priorityName`. Without either, a pull request gets `medium` (100). **`urgent` (or `priorityValue: 0`) restarts lower-priority pull requests that are already testing**, so reserve it for emergencies. See [Priority merging](/merge-queue/optimizations/priority-merging).
 - **Direct to queue**: `direct: true` sends a pull request to the queue before its branch protection is satisfied. See [Direct-to-Queue](/merge-queue/using-the-queue/direct-to-queue).
+- **Merge method**: `squash`, `rebase`, or `mergeCommit`. A pull request uses the queue's `mergeMethod` unless it chose its own while the queue allows choosing. See [Merge method](#merge-method).
 
 ## Authentication
 
@@ -55,6 +56,7 @@ Its `201` response is the pull request; keep its `id` for polling.
   - It targets a different branch from the queue's. A stacked pull request may target another pull request's branch, as long as the stack ends at the queue's branch.
   - A repository ruleset can block it.
   - It's still in another of the repository's queues. Look up the pull request, read `queueEntry.mergeQueueId`, and dequeue it there first.
+  - It chose a [merge method](#merge-method) that isn't allowed.
 - A closed pull request is accepted but stays `notReady`.
 
 To wait for a pull request to merge, poll [`GET /v2/pull-requests/{id}`](/api/pullrequests/get-a-pull-request) every 30 to 60 seconds until `queueEntry.state` is `merged`, `failed`, or `cancelled`, or subscribe to [Merge Queue webhooks](/merge-queue/webhooks). The API itself has no webhooks.
@@ -68,6 +70,23 @@ To wait for a pull request to merge, poll [`GET /v2/pull-requests/{id}`](/api/pu
 
 To find out why a pull request failed, read the latest transition in its [queue-entry history](/api/pullrequests/list-a-pull-requests-queue-entry-state-history) (`direction=newest`). The [failure reason reference](/merge-queue/using-the-queue/handle-failed-pull-requests#failure-reason-reference) explains each `reason`. When a required check failed, `failed.failureCausingChecks` names the checks, and `verificationRunId` leads to the [verification run](/api/mergequeueverificationruns/get-a-verification-run) and its `checks`.
 
+## Merge method
+
+Every pull request merges with the queue's merge method, `config.mergeMethod`, unless it chose its own. A pull request can choose only when the queue's `config.isMergeMethodOverrideEnabled` is `true`. Turn the setting on in the queue's [settings](/merge-queue/administration/advanced-settings#choosing-a-merge-method-per-pull-request), or send `{ "isMergeMethodOverrideEnabled": true }` to [`PATCH /v2/merge-queues/{id}/config`](/api/mergequeues/update-a-merge-queues-configuration) with a key that has **Update Merge Queue settings**.
+
+To choose, send `mergeMethod` as `squash`, `rebase`, or `mergeCommit` when you submit. Choosing needs only the **Merge and cancel PRs** permission:
+
+```bash
+curl -X POST https://api.trunk.io/v2/merge-queues/xK9mP2nQ/pull-requests \
+  -H "Authorization: Bearer $TRUNK_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{ "number": 4901, "mergeMethod": "rebase" }'
+```
+
+To change it while the pull request is queued, send `mergeMethod` to [`PATCH /v2/pull-requests/{id}/queue-entry`](/api/pullrequests/update-a-queued-pull-requests-entry). Send `null` to go back to the queue's method; leave it out to keep the current choice. `queueEntry.mergeMethod` reads the choice back, and is `null` when none is chosen.
+
+Trunk refuses a choice with `422 PR_NOT_ENQUEUEABLE`, and the reason in `message`, when the queue's setting is off and the method differs from the current one, when the pull request is already being merged and the method changes, or when the branch's rulesets don't allow the method.
+
 ## Queue order
 
 List order is not queue order. A queue's pull request list is ordered by when each pull request was first submitted to the queue, newest first, and a resubmission doesn't move it. For the order the queue will test pull requests in, use [`GET /v2/merge-queues/{id}/order`](/api/mergequeues/get-a-merge-queues-dispatch-order). Its lists carry only each pull request's `id`, `number`, `title`, `sha`, and `url`. For state or priority, match by `id` against `GET /v2/merge-queues/{id}/pull-requests?state=pending,testing,testsPassed,pendingFailure`.

merge-queue/using-the-queue/reference.mdx

@@ -24,6 +24,8 @@ og:title: "Submit and cancel PRs in Trunk Merge Queue"
 
     - **Submit:** `/trunk merge`
     - **Cancel:** `/trunk cancel`
+
+    To choose a merge method, if your queue [allows it](/merge-queue/administration/advanced-settings#choosing-a-merge-method-per-pull-request), add `--merge-method=` with `squash`, `rebase`, or `merge` (a merge commit) to `/trunk merge`.
   </Tab>
   <Tab title="GitHub Label">
     Apply a configured **enqueue label** to the pull request on GitHub to submit it automatically. See [Enqueueing by label](#enqueueing-by-label) below.