diff --git a/merge-queue/migrating-from-github-merge-queue.md b/merge-queue/migrating-from-github-merge-queue.md index 9953644c..2c599610 100644 --- a/merge-queue/migrating-from-github-merge-queue.md +++ b/merge-queue/migrating-from-github-merge-queue.md @@ -1,86 +1,87 @@ --- description: >- - Switch from GitHub's native merge queue to Trunk Merge Queue with minimal - disruption to your workflow. + Move a repository from GitHub Merge Queue to Trunk Merge Queue with a clean + same-day switch. Optional cautious route for teams that want to validate + first. --- # Migrate from GitHub Merge Queue -For teams switching from [GitHub Merge Queues](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request-with-a-merge-queue) to Trunk Merge Queue, the process is straight forward. +For teams switching from [GitHub Merge Queues](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request-with-a-merge-queue) to Trunk Merge Queue, the recommended path is a clean same-day switch: set up Trunk, disable GitHub Merge Queue, and announce to your team. {% hint style="success" %} -Looking for a more detailed comparison between Trunk and GitHub's Merge Queues? [Learn more](https://trunk.io/trunk-vs-github-merge-queue) +Looking for a more detailed comparison between Trunk and GitHub's Merge Queues? [Learn more](https://trunk.io/trunk-vs-github-merge-queue) {% endhint %} -*** - -### Turn off GitHub Merge Queue - -To start, you will need to disable the existing merge queue for the target repository. This can be done by navigating to the repository and opening **Settings > Branches >** branch rule **>** toggle **off Require merge queue.** Be sure to click **Save changes** to confirm the settings. - -{% hint style="info" %} -Note that only users with admin permissions can manage merge queues for pull requests targeting selected branches of a repository. More information on [manage merge queues](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule#creating-a-branch-protection-rule) can be found in the GitHub documentation. +{% hint style="warning" %} +Don't run both queues for an extended period. Long-term dual mode means in-flight PRs from both sides preempt each other and your team will see slower merge times overall. Pick one queue. {% endhint %} *** -### Enable Trunk Merge Queue - -Follow the [Getting Started](getting-started/) to setup your repo with Trunk Merge Queue and configure the [settings](administration/advanced-settings.md) for your repository. - -*** +### Migration steps -### Running both merge queues simultaneously +The recommended sequence for admins moving a repository from GitHub Merge Queue to Trunk Merge Queue. -Many teams prefer a gradual migration approach where Trunk Merge Queue runs alongside GitHub Merge Queue before fully switching over. This is a common path for teams migrating from GitHub's merge queue to Trunk and works well for several reasons: +#### 1. Set up Trunk Merge Queue -#### No Disruption to Existing Workflows +Follow [Getting Started](getting-started/) to install Trunk and configure your repository. Configure branch protection rules to include Trunk's status checks, and review [Advanced settings](administration/advanced-settings.md) such as timeouts, batching, and optimistic merging for your repo. -Enabling Trunk Merge Queue does not stop or prevent your current merging flow. GitHub's merge queue will continue to function normally and merge PRs as it always has. Your team can continue using their familiar workflow while you evaluate Trunk Merge Queue. +Keep Trunk's automatic PR comments off for now so developers aren't surprised by comments from a queue they don't yet know about. This setting is under **Merge Queue** tab **>** repository **> Settings >** toggle **off GitHub Comments.** -#### Disable Comments During Evaluation +#### 2. Disable GitHub Merge Queue -To prevent confusion for developers who aren't yet aware of the migration, you can disable the comments Trunk leaves on PRs. This way, developers won't see unfamiliar comments about Trunk Merge Queue while you're still evaluating. +In the GitHub repository, navigate to **Settings > Branches >** branch rule **>** toggle **off Require merge queue.** Click **Save changes** to confirm. -This setting is found under **Merge Queue** tab **>** repository **> Settings >** toggle **off GitHub Comments.** +{% hint style="info" %} +Only users with GitHub admin permissions can manage merge queues for pull requests targeting selected branches of a repository. See GitHub's [managing merge queues](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule#creating-a-branch-protection-rule) documentation for details. +{% endhint %} -#### Trunk Handles External Merges Gracefully +#### 3. Turn on Trunk's PR comments -Trunk Merge Queue understands when a PR is merged outside of its queue (for example, through GitHub's merge queue): +Turn Trunk's automatic PR comments back on under **Merge Queue** tab **>** repository **> Settings >** toggle **on GitHub Comments.** This is when Trunk becomes visible to your team on every PR. -- **If the PR is also in Trunk's queue**: Trunk will automatically mark it as merged on its side. -- **If the PR is not in Trunk's queue**: Trunk will restart any PRs currently in its queue so they can test on top of the new commit. +#### 4. Announce to your team -This ensures that Trunk always tests against the latest state of your target branch, regardless of how PRs are merged. +Share the change with your team. See [Dev-facing announcement copy](#dev-facing-announcement-copy) for a template you can paste into Slack or email, and [Using the Queue](using-the-queue/) for the full developer workflow. *** -### Pre-migration +### Cautious route: validate first -Before migrating fully, it may be useful to evaluate the workflows quietly and confirm settings before converting your repository to an entirely new workflow. +If you want to confirm Trunk's configuration on a few real PRs before disabling GitHub Merge Queue, run a short validation window before doing step 2 above. -Here are some useful steps to get you familiar with the Trunk Merge Queue workflow without disrupting engineers. +1. Complete step 1 (set up Trunk Merge Queue, GitHub Comments toggled off). +2. As an admin, post `/trunk merge` on a handful of representative PRs to confirm Trunk processes them as expected. Watch for required checks running, optimistic merging behavior, timeouts, and any anti-flake protections behaving as you'd expect. +3. Once confident, continue with steps 2 through 4 above. -#### Enable Trunk Merge for testing but with the automatic comments disabled +During this window, most PRs continue merging through GitHub's queue as normal. Only PRs where the admin explicitly posts `/trunk merge` enter Trunk's queue. -While evaluating and testing Trunk Merge Queue for your team, we suggest disabling automatic comments on PRs. This can be done by toggling off GitHub Comments in the Trunk web app. +{% hint style="info" %} +**Safety net.** If a PR ends up enqueued in both queues at once, or if a commit lands on your target branch from outside Trunk while Trunk has in-flight PRs, Trunk handles it correctly: -This setting is found under **Merge Queue** tab **>** repository **> Settings >** toggle **off GitHub Comments.** +* A queued PR merged externally is marked as merged on Trunk's side. +* An external commit on the target branch restarts any of Trunk's in-flight PRs so they re-test on the new target branch head. -#### Make the switch +These are safeguards against accidental collisions during validation, not features that support long-term coexistence. +{% endhint %} -Once you have [configured settings](administration/advanced-settings.md) and tested out the workflow quietly, turn off other merge tools (like [GitHub merge queue](migrating-from-github-merge-queue.md#turn-off-github-merge-queue)), re-enable GitHub comments in the Trunk web app under the **Merge Queue** tab **>** repository **> Settings >** toggle **on GitHub Comments** +*** -{% hint style="info" %} -It is important that a repository is configured to use ONLY Trunk Merge Queue and no other merge queue tools for best results. -{% endhint %} +### Dev-facing announcement copy -#### Share the news +Once you've switched, share the change with your team. Below is a template admins can adapt for Slack or email. -Now that you have migrated to Trunk Merge Queue, be sure to share the workflow with your team, [using-the-queue](using-the-queue/ "mention")as a great place to start. +> **Heads up: we're moving to Trunk Merge Queue.** +> +> Starting \[date], pull requests on `[repo]` will merge through Trunk Merge Queue instead of GitHub's. The day-to-day flow is the same: open a PR, get required checks green, then post `/trunk merge` on the PR instead of clicking GitHub's "Merge when ready" button. +> +> Trunk will leave a comment on each PR with its queue position and status. The full developer workflow is documented at \[link to Trunk's Using the Queue page]. +> +> Questions? Reply in this thread or DM \[admin contact]. *** ### Getting help -If you or your team are running into issues be sure to join the [Trunk Slack community](https://slack.trunk.io/) for assistance. +If you or your team are running into issues, join the [Trunk Slack community](https://slack.trunk.io/) for assistance.