Overhaul concurrency design

[joshlf]

https://gemini.google.com/app/885b561b5b6603f9

Progress

• [test] Capture precise, total command output #258
• Refactor pre-push hook into a pipeline architecture #268
• Flesh out design, using this Gemini conversation for inspiration
• Split README.md design section into its own file
• Update this design doc to document the "single linearization point" design described below
• When git push needs to be split into multiple calls, print a warning to stderr that concurrency guarantees are weakened
• Refactor pre-push hook around this linearization point so that the control flow makes this critical point clear
• In the pre-push hook, check to see whether this push operation reorders PRs (relative to the state of GH) – if so, re-parent PRs to main first
  • Need to confirm that this design can never result in perma-closed PRs, even under contention

Details

• Needs to be a single "linearization point" where all operations either fully succeed or fully fail
• It's okay for the GH repo to be in a weird, inconsistent state at this point, but future git push operations must be able to "heal" from this inconsistency back to the correct, complete state
• The ground truth for all operations only lives in Git, not in PRs. In particular:
  • Git graph
  • Commit messages (which contain GHerrit PR IDs)
  • Git tags (which contain versions)
• These assume that all updates happen during a single, atomic git push operation (invoked from the GHerrit pre-push hook). In edge cases where there are too many commits, and we need to split this git push into multiple calls:
  • We still do the right thing when there is no racing (ie, in the single-user case)
  • We may have concurrency bugs under contention