|
| 1 | +# Rollup Procedure |
| 2 | + |
| 3 | +## Background |
| 4 | + |
| 5 | +The Rust project has a policy that every pull request must be tested after merge |
| 6 | +before it can be pushed to master. As PR volume increases this can scale poorly, |
| 7 | +especially given the long (~3.5hr) current CI duration for Rust. |
| 8 | + |
| 9 | +Enter rollups - changes that small, not performance sensitive, or not platform |
| 10 | +dependent are marked with the `rollup` command to bors (`@bors r+ rollup` to |
| 11 | +approve a PR and mark as a rollup, `@bors rollup` to mark a previously approved |
| 12 | +PR, `@bors rollup-` to un-mark as a rollup). 'Performing a Rollup' then means |
| 13 | +collecting these changes into one PR and merging them all at once. The rollup |
| 14 | +command accepts three values `always`, `maybe`, and `never`. `@bors rollup` is |
| 15 | +equivalent to `rollup=always` (which will indicate that a PR should always be |
| 16 | +included in a rollup), and `@bors rollup-` is equivalent to `@bors rollup=maybe` |
| 17 | +which is used to indicate that someone should try rollup the PR. `rollup=never` |
| 18 | +indicates that a PR should never be included in a rollup, this should generally |
| 19 | +only be used for PRs which are large additions or changes which could cause |
| 20 | +breakage or large perf changes. |
| 21 | + |
| 22 | +You can see the list of rollup PRs on Rust's [Homu queue], they are |
| 23 | +listed at the bottom of the 'approved' queue with a priority of 'rollup' meaning |
| 24 | +they will not be merged by themselves until everything in front of them in the |
| 25 | +queue has been merged. |
| 26 | + |
| 27 | +## Making a Rollup |
| 28 | + |
| 29 | +1. Using the interface on [Homu queue], select a few pull requests and then use |
| 30 | + "rollup" button to make one. (The text about fairness can be ignored.) |
| 31 | +2. Use the `@bors r+ rollup=never p=<NUMBER_OF_PRS_IN_ROLLUP>` command in the |
| 32 | + pull request thread. |
| 33 | +3. Mark the pull request with the label `rollup`. |
| 34 | +4. If the rollup fails, use the logs rust-highfive (really it is |
| 35 | + rust-log-analyzer) provides to bisect the failure to a specific PR and do |
| 36 | + `@bors r-`. If the PR is running, you need to do `@bors r- retry`. Otherwise, |
| 37 | + your rollup succeeded. If it did, proceed to the next rollup (every now and |
| 38 | + then let `rollup=never` and toolstate PRs progress). |
| 39 | +5. Recreate the rollup without the offending PR starting again from **1.** |
| 40 | + |
| 41 | +## Selecting Pull Requests |
| 42 | + |
| 43 | +This is something you will learn to improve over time. Some basic tips include |
| 44 | +(from obvious to less): |
| 45 | + |
| 46 | +1. Avoid `rollup=never` PRs (these are red in the interface). |
| 47 | +2. Include all PRs marked with `rollup=always` (these are green). Try to check |
| 48 | + if some of the pull requests in this list shouldn't be rolled up — in the |
| 49 | + interest of time you can do so sometimes after you've made the rollup PR. |
| 50 | +3. Avoid pull requests that touch the CI configuration or bootstrap. |
| 51 | + (Unless the CI PRs have been marked as `rollup`. -- see 2.) |
| 52 | +4. Avoid having too many large diff pull requests in the same rollup. |
| 53 | +5. Avoid having too many submodule updates in the same rollup (especially LLVM). |
| 54 | + (Updating LLVM frequently forces most devs to rebuild LLVM which is not fun.) |
| 55 | +6. Do not include toolstate PRs like those fixing Miri, Clippy, etc. |
| 56 | +7. Do include docs PRs (they should hopefully be marked as green). |
| 57 | + |
| 58 | +## Failed rollups |
| 59 | +If the rollup has failed, run the `@bors retry` command if the |
| 60 | +failure was spurious (e.g. due to a network problem or a timeout). If it wasn't spurious, |
| 61 | +find the offending PR and throw it out by copying a link to the rust-highfive comment, |
| 62 | +and writing `Failed in <link_to_comment>, @bors r-`. Hopefully, |
| 63 | +the author or reviewer will give feedback to get the PR fixed or confirm that it's not |
| 64 | +at fault. |
| 65 | + |
| 66 | +Once you've removed the offending PR, re-create your rollup without it (see 1.). |
| 67 | +Sometimes however, it is hard to find the offending PR. If so, use your intuition |
| 68 | +to avoid the PRs that you suspect are the problem and recreate the rollup. |
| 69 | +Another strategy is to raise the priority of the PRs you suspect, |
| 70 | +mark them as `rollup=never` and let bors test them standalone to dismiss |
| 71 | +or confirm your hypothesis. |
| 72 | + |
| 73 | +If a rollup continues to fail you can run the `@bors rollup=never` command to |
| 74 | +never rollup the PR in question. |
| 75 | + |
| 76 | +[Homu queue]: https://buildbot2.rust-lang.org/homu/queue/rust |
0 commit comments