Merge queue best practices

If your engineering team creates a large number of pull requests (PRs) every day in the same git repo, then you can benefit from using a merge queue. A merge queue safely and efficiently merges PRs into the base branch, pulling in and running checks on each PR to avoid merge conflicts. If the checks run successfully, the queue automatically rebases each PR onto the main branch and merges it automatically.

However, like any tool, using merge queues effectively requires following some best practices. This mini guide lists a few best practices to help you get the most out of a merge queue.

General best practices

Regardless of how many PRs your team submits per day or how long your continuous integration (CI) checks take to run, you should keep in mind the following best practices to optimize your merge queue setup:

Clear code review guidelines

Establish clear expectations for code review by outlining the criteria for approval. This might involve code style, adherence to coding standards, unit test coverage, and proper documentation. Transparent guidelines ensure consistent code quality and minimize the chances of regressions being introduced through the merge.

It's especially important to correctly review each PR when merging through a merge queue, as it may later become difficult to find the change that lead to a regression so you can roll it back.

Automated checks

Use continuous integration & continuous delivery (CI/CD) pipelines to automate essential checks on queued PRs. These checks include building the code with the proposed changes, running linting tools to identify style & syntax issues, and executing unit tests to ensure code functionality. Automating these checks saves developers' time when testing their code and allows the queue to identify potential problems before merging.

Small, focused PRs

Large, sweeping changes can be difficult to review and merge. Encourage developers to break down their work into smaller, focused PRs. This makes code review more efficient, identifies potential issues earlier, and simplifies the merging process within the queue. Additionally, this method also makes it easier to remove small groups of changes (grouped together in a PR) out of a merge queue if a check fails instead of having to remove one large PR that contains many valid changes but a few breaking changes.

Clear conflict management strategy

Merge conflicts, while less likely to happen with well-defined PRs, can always arise. Define a clear strategy for handling conflicts when they occur. This might involve assigning ownership to specific developers based on the conflicting code sections or establishing communication protocols to resolve conflicts promptly.

Healthy queue length and throughput

Keep an eye on the length of your merge queue and the overall throughput (number of PRs merged per unit of time). If the queue becomes too long, it can lead to delays in merging and reduce development velocity. Analyze your workflow and adjust practices (eg encouraging right-sized PRs that make code reviews easier while not adding to a very long merge queue either) to maintain a healthy queue length and smooth merging process.

Using merge queues correctly across team sizes

The optimal approach to using a merge queue can vary depending on your team's size. If you're running a small team (eg up to 10 developers), you probably don't need to use a merge queue unless you're creating a high volume of PRs. You should focus on clear communication and collaboration during manual code reviews to minimize conflicts. If you choose to implement a merge queue, consider a lightweight queue setup - complex features such as parallel CI and batching might be an overkill for smaller teams.

If your team is mid-size (eg 10-50 developers), a merge queue can help you automate checks, enforce code quality standards, and reduce merge conflicts. You can also use features like stack-aware merging (if available) to merge stacked PRs faster.

Large teams (eg >50 developers) working in the same repo greatly benefit from using a merge queue. To get the most out of using one, large teams should configure queue optimizations like parallel CI and batching to handle high volume of PRs. Considering the scale and activity of such teams, they should also implement robust conflict resolution strategies and agree upon clear communication channels to handle large-scale merges smoothly.

By keeping these points in mind, you can most effectively configure your merge queue according to your team's size and activity requirements.