Commit Management

Because CI takes so long, we use a bot to facilitate landing changes in branches under branch protection rules such as master and release related branches.

The bot and merge process is currently coordinated by Mergify, and triggered by automerge:* labels. While GitHub will still allow you to manually land a PR if all conditions are met, we ask that you do not use the GitHub "Merge" UI button or GitHub CLI to land a PR, and solely rely on the Mergify system.

Pull request "merge" instructions

Once the PR is ready to land, you can apply an automerge:* label to instruct Mergify to "merge" the PR once all conditions are satisfied. The conditions are as follow:

• One approving reviewer (with write permissions), no request for changes.
• All required checks pass (denotated as "Required" in the list of checks)

The following merge modes are available:

• automerge:squash - Merge the target branch into the PR branch (if not up to date), then squashes all commits of the PR into a single commit applied directly to the target branch.
• automerge:rebase - Rebase all commits (with autosquash for commits with fixup!-style messages) onto the target branch, then create a merge commit of this rebased branch onto the target branch.
• automerge:merge - Merge the target branch into the PR branch (if not up to date), then create a merge commit of the updated PR branch into the target branch

The recommended mode depends on the use case and individual constraints:

• merge if you must keep the original commits intact, such as carrying signed commits or merging a branch containing tags (like a release branch)
• squash if the PR started as a single commit, or is meant to be a single, small, atomic change
• rebase for all other cases (considered the default)

CI and Mergify process

All GitHub actions (CI jobs) run on a simulated merge of the PR branch onto the target branch. If there are merge conflicts, the actions do not run, and merge conflicts must first be manually resolved (e.g. merge the target branch locally into the PR branch, resolve conflicts, and push the branch).

Once all conditions are satisfied, aka once the PR is approved and all required status checks pass, Mergify will add the PR to the merge queue.

Once the PR is at the top of the merge queue, Mergify will update the PR according to the merge mode (rebase or merge), re-run required checks if needed, run integration tests, then merge the PR following the mode requested (squash or merge).

Integration tests are CI jobs that run only once a PR is ready for merge (up-to-date and with an automerge:* label applied). They are more expensive than other CI jobs, and fail less often so we avoid running them for every push. If a PR may potentially cause the integration tests to fail, the author can apply the force:integration label to run these tests with every PR push.

If you'd like, you can see the current merge queue at https://dashboard.mergify.io

Protobuf / Breakage

One of our CI tests verifies that there have been no breaking changes in the Protobuf .proto files. If you have made a breaking change but still want the PR to be merged, add a proto:expect-breakage label to it, in addition to the above automerge:* label. Then Mergify will only land the PR if there was a breaking proto change. If there really wasn't a breaking change, remove the proto:expect-breakage label; you don't need it.