Skip to content

docs: document the concurrency model, convergence guarantees, and non-goals - #541

Merged
joshua-temple merged 1 commit into
mainfrom
docs/concurrency-model-and-non-goals
Jul 9, 2026
Merged

joshua-temple merged 1 commit into
mainfrom
docs/concurrency-model-and-non-goals

Conversation

@joshua-temple

Copy link
Copy Markdown
Collaborator

What

Documents the concurrency behavior shipped in this campaign, and states the deliberate non-goals so users are not surprised.

  • internals/architecture.md - a Concurrency and convergence section: per-component concurrency-group isolation (no cross-component cancel); the optimistic read-modify-write with re-apply that all finalize paths use so concurrent component finalizes converge without clobbering siblings; the bounded jittered retry and its cascade-state-write convergence markers; why extra_triggers.merge_group on the side-effecting orchestrate lane is rejected in favor of merge_queue.enabled; and how extra_paths/shared_paths thread a shared change to its consumers.
  • Non-goals (same page): no intra-repo component ordering, no per-component state files, no same-component cross-lane serialization - framed as intentional design.
  • CONTRIBUTING.md: a breaking generator or validation change (rejecting a previously-valid manifest shape) must scan and migrate the fleet example repos in the same change, since the fleet repin regenerates every example repo with the rc binary before any suite runs.

Verification

Docs site builds (26 pages). go build and go test ./... green. Content verified against the shipped behavior; single-sourced with links. Docs + CONTRIBUTING only, no product code.

…-goals

Add a concurrency-and-convergence explanation to the internals architecture page: per-component concurrency-group isolation, the optimistic read-modify-write with re-apply that all finalize paths use, the bounded jittered retry and its convergence markers, why merge_group on the side-effecting orchestrate lane is rejected in favor of merge_queue.enabled, and how extra_paths and shared_paths thread a shared change to the components that consume it. State the deliberate non-goals: no intra-repo component ordering, no per-component state files, no same-component cross-lane serialization. Codify in CONTRIBUTING that a breaking generator or validation change must scan and migrate the fleet example repos in the same change, since the fleet repin regenerates every example repo with the release-candidate binary before any suite runs.

Signed-off-by: Joshua Temple <joshua.temple@stablekernel.com>
@joshua-temple
joshua-temple merged commit 4c8e401 into main Jul 9, 2026
16 checks passed
@joshua-temple
joshua-temple deleted the docs/concurrency-model-and-non-goals branch July 9, 2026 16:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant