Skip to content

Commit 4797781

Browse files
Sakib25800Sakib25800
committed
Update design docs with auto builds
1 parent bcd090e commit 4797781

File tree

1 file changed

+84
-0
lines changed

1 file changed

+84
-0
lines changed

‎docs/design.md

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -113,6 +113,90 @@ the branch to parent, and then again after merging the PR commit).
113113

114114
Note that `automation/bors/try-merge` should not have any CI workflows configured! These should be configured for the `automation/bors/try` branch instead.
115115

116+
## Auto builds
117+
The merge queue is an automated system that processes approved pull requests and merges them into the base branch after
118+
ensuring they pass all CI checks. PRs are approved using the `@bors r+` command and then "queued" automatically.
119+
120+
Here is a sequence diagram that describes what happens when a PR is approved and enters the merge queue:
121+
122+
```text
123+
+-----+ +-------+ +-----+ +-----+ +---------+
124+
| PR | | bors | | GHA | | DB | | teamAPI |
125+
+-----+ +-------+ +-----+ +-----+ +---------+
126+
| | | | |
127+
| @bors r+ (via webhook) | | | |
128+
|---------------------------------->| | | |
129+
| | | | |
130+
| | check user permissions | | |
131+
| |------------------------------------------------------>|
132+
| | | | |
133+
| | store approval in DB | | |
134+
| |-------------------------------------------->| |
135+
| | | | |
136+
| comment: "Commit abc123 approved" | | | |
137+
|<----------------------------------| | | |
138+
| | | | |
139+
| | (every 30s: process merge queue) | | |
140+
| | | | |
141+
| | merge PR with base to `auto-merge` | | |
142+
| |------------------------------------>| | |
143+
| | | | |
144+
| | push merge commit to `auto` | | |
145+
| |------------------------------------>| | |
146+
| | | | |
147+
| | create check run on PR head | | |
148+
| |------------------------------------>| | |
149+
| | | | |
150+
| | store auto build | | |
151+
| |-------------------------------------------->| |
152+
| | | | |
153+
| comment: ":hourglass: Testing.." | | | |
154+
|<----------------------------------| | | |
155+
| | | | |
156+
| | workflow started | | |
157+
| |<------------------------------------| | |
158+
| | | | |
159+
| | store workflow in DB | | |
160+
| |-------------------------------------------->| |
161+
| | | | |
162+
| | workflow completed | | |
163+
| |<------------------------------------| | |
164+
| | | | |
165+
| | update workflow status | | |
166+
| |-------------------------------------------->| |
167+
| | | | |
168+
| | query check suites for commit | | |
169+
| |------------------------------------>| | |
170+
| | | | |
171+
| | (wait for all check suites) | | |
172+
| | | | |
173+
| | check suite completed | | |
174+
| |<------------------------------------| | |
175+
| | | | |
176+
| | update build status | | |
177+
| |-------------------------------------------->| |
178+
| | | | |
179+
| | update check run on PR head | | |
180+
| |------------------------------------>| | |
181+
| | | | |
182+
| | fast-forward base branch | | |
183+
| |------------------------------------>| | |
184+
| | | | |
185+
| comment: ":sunny: Test successful"| | | |
186+
|<----------------------------------| | | |
187+
| | | | |
188+
```
189+
190+
The merge queue first merges the PR with the latest base branch commit in `automation/bors/auto-merge`, then pushes
191+
this merged commit to `automation/bors/auto` where CI tests run. If all tests pass, the base branch is fast-forwarded
192+
to the merge commit.
193+
194+
Only one auto build runs at a time to ensure that each PR is tested against the same branch state it will be merged into,
195+
preventing the problem where two PRs pass tests independently but fail when combined.
196+
197+
Note that `automation/bors/auto-merge` should not have any CI workflows configured! These should be configured for the
198+
`automation/bors/auto` branch instead.
199+
116200
## Recognizing that CI has succeeded/failed
117201
With [homu](https://github.com/rust-lang/homu) (the old bors implementation), GitHub actions CI running repositories had
118202
to use a "fake" job that marked the whole CI workflow as succeeded or failed, to signal to bors if it should consider

0 commit comments

Comments
 (0)