Skip to content

Commit e600092

Browse files
jdclaude
andcommitted
docs: add source links and citations
- Link Google Testing Blog for flake rate guidance - Link ACM research on developer productivity - Link Gloria Mark's research paper on focus interruptions - Soften unsourced statistical claims - Cross-reference companies page for queue metrics Co-Authored-By: Claude Opus 4.5 <[email protected]> Change-Id: I61e7f7d8a938fadfe7f926346efd2aca41434345 Claude-Session-Id: 43e5bb59-bfd1-4f17-982a-657235752c0d
1 parent 5d76c33 commit e600092

File tree

4 files changed

+5
-5
lines changed

4 files changed

+5
-5
lines changed

src/content/docs/decision/failure-scenarios.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -205,7 +205,7 @@ Every time a developer is blocked, they have to:
205205
2. Investigate or wait
206206
3. Resume their original work (losing context)
207207

208-
Research by Gloria Mark at UC Irvine shows it takes **23 minutes** to regain focus after an interruption. A broken main interrupts everyone.
208+
[Research by Gloria Mark at UC Irvine](https://www.ics.uci.edu/~gmark/chi08-mark.pdf) shows it takes **23 minutes** to regain focus after an interruption. A broken main interrupts everyone.
209209

210210
### Compound Delays
211211

src/content/docs/decision/prerequisites.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@ flowchart TD
3939

4040
### Target: <2% flake rate
4141

42-
Before adopting a merge queue, your test suite should have a flake rate under 2%. That means fewer than 1 in 50 runs fails randomly.
42+
Before adopting a merge queue, your test suite should have a flake rate under 2%. That means fewer than 1 in 50 runs fails randomly. [Google's testing guidelines](https://testing.googleblog.com/2016/05/flaky-tests-at-google-and-how-we.html) discuss how they tackled this at scale.
4343

4444
### How to measure
4545

@@ -96,7 +96,7 @@ CI speed matters because of the **feedback loop**. When a PR fails in the queue,
9696

9797
### Ideal: <20 minutes
9898

99-
Under 20 minutes keeps the feedback loop tight. Developers can fix issues and re-queue within the same focus session.
99+
Under 20 minutes keeps the feedback loop tight. Developers can fix issues and re-queue within the same focus session. [Research on developer productivity](https://queue.acm.org/detail.cfm?id=3595878) shows that fast feedback cycles significantly improve developer experience.
100100

101101
But not everyone can achieve this—and that's okay. If your CI is slower, merge queue features can help:
102102

src/content/docs/use-cases/high-velocity-teams.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,7 @@ Not all PRs are equal. [Priority management](/features/priority-management/) let
7272

7373
## Measuring Queue Health
7474

75-
Track these metrics to know if your queue is keeping up:
75+
Track these metrics to know if your queue is keeping up. These thresholds are based on patterns observed at [high-performing teams like GitHub, Shopify, and Uber](/introduction/companies-using-merge-queues/)—adjust for your context:
7676

7777
| Metric | Healthy | Warning | Critical |
7878
|--------|---------|---------|----------|

src/content/docs/use-cases/long-ci-pipelines.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ flowchart LR
3333
Full --> Merge["Merge"]
3434
```
3535

36-
- **PR CI**: Lint, unit tests, build — catches 90% of issues in 5 minutes
36+
- **PR CI**: Lint, unit tests, build — catches most issues quickly (typically 80-90%)
3737
- **Queue CI**: Integration tests, E2E, full validation — runs only for approved PRs
3838

3939
Engineers get fast feedback. The queue runs thorough checks. Both needs met.

0 commit comments

Comments
 (0)