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.