The Hitchhiker's Guide to Servo Contributor - Part III
February 23, 2020
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.