From 4d0c3aecf0f5c5597cb6d7896bdb76e686e2acb0 Mon Sep 17 00:00:00 2001 From: Preetam Dwivedi Date: Wed, 7 Oct 2026 14:39:47 -0700 Subject: [PATCH] docs(demo): document BURST mode in the quickstart MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary ### Why? `make demo-requests BURST=true` (create every change, then enqueue them together) works and is tested, but the quickstart's option list skipped it, so it was only discoverable from `make help` or the Makefile. ### What? - Add `BURST=true` to the `demo-requests` options list in `doc/howto/QUICKSTART.md`. - Add a paragraph on what burst does and how to get a true spike (`COUNT=100 BURST=true CONCURRENCY=100`), since enqueues are still bounded by `CONCURRENCY`; notes GitHub rate limits and that it doesn't apply with `STACKED` or `LAND=false`. ## Test Plan ✅ `make lint-fmt` (`lint-message-id` fails locally on an untracked `pkg/mod/` module cache, unrelated) ✅ Behavior checked against `service/submitqueue/demo/run.go` (`createAndSubmit`, `forEachChange`) --- doc/howto/QUICKSTART.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/howto/QUICKSTART.md b/doc/howto/QUICKSTART.md index d8892b71b..1ee40c445 100644 --- a/doc/howto/QUICKSTART.md +++ b/doc/howto/QUICKSTART.md @@ -63,11 +63,14 @@ make demo-requests FOLDERS=50 # git/github: spread changes across more make demo-requests FILES=8 # git/github: wider changes, more files each make demo-requests CONCURRENCY=1 # create them one at a time make demo-requests STACKED=true # one stack, enqueued as a single request +make demo-requests BURST=true # create every change first, then enqueue them together make demo-requests LAND=false # create only, print the command to enqueue them ``` Independent changes are created **five at a time** by default (`CONCURRENCY`), because creating them serially is most of what a large run spends its time on and it delays the overlap the demo exists to show. A stack ignores the setting: each of its changes is based on the branch before it, so the next cannot be cut until the previous head exists. +By default each change is enqueued the moment it exists, so a large run trickles into the queue at the pace changes are created. `BURST=true` holds every request back until all the changes exist, then enqueues them together — the way to see the queue absorb a spike. The enqueues still go out `CONCURRENCY` at a time, so raise it with `COUNT` for a true spike: `make demo-requests COUNT=100 BURST=true CONCURRENCY=100`. On github that also opens 100 pull requests in parallel, which can trip GitHub's secondary rate limits. Burst applies to independent changes only; `STACKED=true` already lands as one request, and `LAND=false` enqueues nothing. + On git/github, a change touches several files rather than one, each committed separately, so it arrives as a multi-file, multi-commit change — closer to a real one, and enough to exercise replaying a range of commits. `FILES` sets the floor (default 3); the actual count varies a little above it, derived from the run tag so replaying a tag reproduces the same run. On git/github, every change writes all of its files into one folder under `demo/`, and `FOLDERS` decides how many folders there are to land in — by default a number between five and ten, picked per run. That is what makes a run interesting rather than uniform, because `demo-queue` uses the `pathoverlap` analyzer keyed on the directory: two changes landing in the same folder are batched in order and the second speculates on the first, while changes in different folders go out beside each other. A run prints the number it picked, and repeating a run tag reproduces the same collisions.