Describe the rollup process

Author: aidanhs

index.md

@@ -57,4 +57,6 @@ PRs against [rust-lang-nursery/rust-forge].
 
 * [PR Triage Procedure](pr-triage-procedure.html)
 
+* [Performing a Rollup](performing-a-rollup.html)
+
 * [Homu/Bors Syntax](https://buildbot2.rust-lang.org/homu/)

performing-a-rollup.md

@@ -0,0 +1,55 @@
+---
+layout: default
+title: Performing a Rollup
+---
+
+# Rollups
+
+## Background
+
+The Rust project has a policy that every PR must be tested after merge before it can
+be pushed to master. As PR volume increases this can scale poorly, especially given
+the 2hr30min current CI duration for Rust.
+
+Enter rollups - low risk changes (often doc fixes or other non-functional changes)
+are marked with the `rollup` command to bors (`@bors r+ rollup` to approve a PR
+and mark as a rollup, `@bors rollup` to mark a previously approved PR, `@bors rollup-`
+to unmark as a rollup).
+'Performing a Rollup' then means collecting these changes into one PR and merging
+them all at once.
+
+You can see the list of rollup PRs on https://buildbot2.rust-lang.org/homu/queue/rust -
+they are listed at the bottom of the 'approved' queue, with a priority of 'rollup',
+meaning they will not be merged by themselves until everything in front of them in the
+queue has been merged.
+
+## Procedure
+
+Prerequisites: `r+` permission on the Rust repo, a fork of `rust-lang/rust`
+under your GitHub username.
+
+ - Visit https://buildbot2.rust-lang.org/homu/queue/rust.
+ - If there are >= 10 rollup priority PRs, you should probably create a rollup.
+ - Look at the current PR being tested:
+   - If it has a priority >0, do not create a rollup until it's complete.
+   - Check how long bors commented with 'Testing commit' - if the test is probably
+     going to finish soon (e.g. it's been over two hours), come back after 30min
+     and it should be done.
+ - Notify the #rust-infra IRC channel.
+ - Press the 'Create a rollup' button near the top left of the queue status page.
+ - (first time: Authorise the github permissions)
+ - Wait for a minute while the rollup is created on the `rollup` branch of your repo
+   and the PR is submitted for you.
+ - Comment with `@bors r+ p=1`. This will put the PR above any 'normal' PRs, but
+   below 'urgent' PRs.
+ - Comment on the PR currently being tested with `@bors retry`. This will prompt
+   bors to stop the current test, allowing it to pick up the new top of the queue -
+   the rollup.
+
+## Failed rollup
+
+Close the PR, figure out if the failure was spurious - if so, create a new PR,
+if not, find the possible candidate PR(s) and unmark it (them) as rollups with
+`@bors rollup-`, commenting on the PR with the error. Hopefully the author or
+a reviewer will give feedback to get the PR fixed or confirm that it's not at
+fault.