...

Bors is only configured to work for the master branch. For all other branches, manually merge using the GitHub Merge button.

Priority

Generally you shouldn’t provide a priority for your PR when merging with bors. As an exception to this rule, some PR’s should be merged with the standard priority p=99.

Pull requests should be bors’ed with the standard priority 99 (bors r+ p=99) if and only if they a) skip or fix a flaky test or otherwise make CI more stable, and b) the flakiness being fixed is somewhat likely to be encountered in CI or as part of a bors (staging) CI run.

The rationale for these criteria is that bors splits up batches by priority. Should you choose a higher priority than all other PR’s in the queue, then bors will put the PR in a batch by itself, eschewing anything else already in the queue. This is not desirable unless that PR fixes an important issue that could conceivably be encountered in a staging build. If not, then all the other (potentially more important) PR’s in the queue were “jumped” for no reason. We choose one standard priority number 99 (arbitrarily) as bors can group together PR’s with the same priority, so if there are 4 test-skip PR’s in the queue and 6 other PR’s, bors knows to batch the 4 test-skip PR’s together and then only try merging the other 6 PR’s after the fact.

The criterion (b) is somewhat vague by design. If you’re in doubt, setting p=99 is probably OK especially if the flake has already been seen several times in CI or in automation. If the flake is encountered only under rare circumstances then it’s probably not necessary to configure a higher priority, and we benefit from letting the queue progress normally.

In general, there is no need to use a non-standard priority other than p=99 or the default. Do not set a high priority just because you would like your change to get in faster: while it may be convenient for you, you end up slowing down everyone else (and in all likelihood you are not saving yourself that much time anyway).

Using single on, even with p=99, is not necessary. In general, we want different PR’s with the same priority to be batched together, and single on disables this desirable behavior.

The above policy applies broadly and in general across PR’s to cockroach. However, breaking these rules can be legitimately useful at times for solving operational problems, or for fast-tracking very high-priority changes that legitimately need to take precedence over everything else for a reason unrelated to CI stability. If you think your PR merits an exception to the policy, ask in the #dev-inf channel to make sure.

FAQ

Craig (bors) told me "Permission denied"!

• If you run bors and get a “Permission denied” response, go to #dev-inf and ask them to:

  • 1. explicitly add you to the access list for cockroach 

  • 2. click Update for the Reviewers list in bors

Other FAQs:

• How is Bors configured? There's not many configuration options, but what there is can be found in bors.toml in the .github directory.

• When does Bors process the config file? At the time commands are issued, Bors looks for a bors.toml in the PR to be merged. This means if you haven't changed it, the config file from your PR's target branch is used.

• Is there a log of what Bors does somewhere? Yep! For this repo, you can find it here.

• How do I add Craig to other repos? Craig is already listening to all the repos under @cockroachdb. There are two steps to making Craig respond to commands somewhere else: part one is to add a bors.toml config file to the repo that tells Bors what CI status to wait on, and part two is adding everyone as reviewers on the repo's settings page on the Bors dashboard.Craig told me "Permission denied"! You are not currently a reviewer, so just ask someone who is to add you to the list of reviewers on the settings page.

• Should I use bors for backports? No, use the green merge button instead.

• My question isn't answered here! Ask on the mailing list, or if you're an internal Cockroach dev, on Slack in the channel #bors.

...