The Hitchhiker's Guide to Servo Contributor - Part III

Preface

When working on an OSS project, knowing its CI works is quite important so that contributors can know how their implementation / fix will be shipped.

In Servo, we use a bot called bors-servo to help us to ship PRs into master branch.

What is bors-servo?

bors-servo is a fork of homu.

Homu is a re-implementation / extension of bors and the bors-servo fork fixes some bugs in homu and has some additional features.

bors is first introduced by Graydon Hoare and it mainly applies Ben Elliston’s The Not Rocket Science Rule.

Basically, no matter bors-servo, homu or bors, they share the same rule:

The Not Rocket Science Rule Of Software Engineering:

automatically maintain a repository of code that always passes all the tests

Homu: The Not Rocket Science

The rule sounds pretty easy, right? but sometimes it doesn’t.

Let’s take a look at this example:

When engineer A sends a PR to rename function foo to function bar and engineer B sends another PR to call function foo in somewhere, both of them will get passing CI in their PRs.

However, when both PRs get merged, they will have a broken master.

How can Homu help us in this case?

Homu will always run CI with latest master before merging PR.

After reviewers approve the PR, Homu will add the PR into its queue and run CI tests in the queue in order like following picture.

There are some PRs with status success, pending and approved.

Let’s take this picture as an example. The PR #24429 is running CI tests with pending status and PR #23850 pending with try permission.

All the approved PRs are waiting for #24429 to be done. So, if the next PR has conflicts to the previous merged PR, it would not be mergeable and would be skipped to next PR.

In short, Homu will run CI tests for approved PR sequentially and also merge the PRs sequentially.

What does the try mean?

One of the benefits from Homu is try command. We can just try the CI tests before adding the PR to approved queue.

While Homu will run tests sequentially for merging PRs, if we just wanna try the CI tests and queue it with approved PRs, it might be a heavy queue and block some other important features to be merged.

Instead of queueing approved tasks and try tasks together, Homu will have a different queue to run those try CI tests.

This is useful when we send a PR and just want to confirm if there’s anything we need to update (ex. some wpt tests are surprisingly fixed).

bors commands

Not only triggering CI by r+ or try, we can also cancel the triggered CI by the - keyword.

Kind
Approval	r+	r-
Try	try	try-

For example, if a PR is approved accidentally, then another reviewer can cancel the approval by r-.

Run specific platform wpt tests

As mentioned above, try leverages the power of “just try; not merge” so we can see the tests result as soon as possible.

Servo is a browser engine which means we have several target platforms. With try, it will trigger tests for all platform (ex. linux, windows, macOS, android, etc.).

So, how can we only trigger try command for a specific platform?

The most common one is @bors-servo try=wpt. With try=wpt, we can trigger wpt tests on linux platform.

Other than wpt command, we have other supported commands for try.

Supported Commands

We can basically see them as two categories.

Platform name commands: only trigger build and test-tidy in CI

wpt-* commands: trigger both build and wpt tests for the platform (wpt implies linux here)

Supported Commands
linux
mac
windows
android
magicleap
arm
wpt
wpt-2020
wpt-mac
wpt-android

(Homu will tell you what kind of commands are supported if wrong command is triggered)

These commands would be helpful if we want to only trigger the CI for specific platforms.

Setup your own bors

For Servo team and Rust team, they have their own forked homu repo and hosted under Mozilla’s infrastructure.

If you want to setup your own bors, you can follow the instructions to set it up and host on your own server.

Or, if you’re using GitHub, you can use bors-ng/bors-ng. It’s a GitHub app so you can easily enable it and use it!

Conclusion

Continuous Integration is pretty important for software engineering. After contributing to Servo, I started to learn how bors works and found it quite helpful for the reviewing process.

Also, with the homu way, it helps a lot for many OSS projects because most people collaborate between cross timezone. It becomes important that we can test the PR with latest master so that we can avoid shipping a broken feature into the project earlier.