Skip to content

(doc)stovepipe: build and buildsignal pipeline steps#336

Open
roychying wants to merge 1 commit into
uber:mainfrom
roychying:chenghan.ying/stovepipe-build/buildsignal-doc
Open

(doc)stovepipe: build and buildsignal pipeline steps#336
roychying wants to merge 1 commit into
uber:mainfrom
roychying:chenghan.ying/stovepipe-build/buildsignal-doc

Conversation

@roychying

@roychying roychying commented Jul 10, 2026

Copy link
Copy Markdown
Contributor

Why?

Stovepipe's pipeline had design docs for process but nothing for the two stages downstream of it - build (triggers the build-runner) and buildsignal (polls it to completion). Both stages needed a documented contract before implementation could start, in particular because stovepipe can't reuse SubmitQueue's BuildRunner interface as-is: SubmitQueue validates stacks of batches, stovepipe validates a single URI against a baseline, and that mismatch has to be resolved deliberately rather than discovered mid-implementation.

What?

  • doc/rfc/stovepipe/steps/build.md (new): documents the build stage end to end - the trigger-only algorithm, idempotency posture under at-least-once redelivery, error classification, edge cases (head == last-green, Phase 2 re-triggers), and the new Build entity/BuildStore/queue contract it needs. Defines the stovepipe BuildRunner contract (design sketch) with URI-based Trigger(headURI, baseURI, metadata) instead of SubmitQueue's batch-based trigger, explains why the contracts are kept separate (materialize-vs-checkout mismatch, baseline semantics batches can't express, URI ownership), and lays out - as open discussion, not settled decisions - alternative shapes for sharing the contract (single platform-level interface, metadata-smuggled scope, shared-backend-thin-contracts) and alternatives for how the build id could be keyed/deduped.
  • doc/rfc/stovepipe/steps/buildsignal.md (new): documents the buildsignal poll loop - reusing SubmitQueue's buildsignal shape (poll cadence, PublishAfter-not-Nack primitive, error classification) pipe diverges: it only forwards to record once terminal

Test Plan

N/A

Issue

@roychying roychying requested review from a team, behinddwalls and sbalabanov as code owners July 10, 2026 21:04
@CLAassistant

Copy link
Copy Markdown

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.


chenghan.ying seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
You have signed the CLA already but the status is still pending? Let us recheck it.

@roychying roychying force-pushed the chenghan.ying/stovepipe-build/buildsignal-doc branch 2 times, most recently from 112337e to 1abb551 Compare July 10, 2026 22:47
@roychying roychying force-pushed the chenghan.ying/stovepipe-build/buildsignal-doc branch from 1abb551 to 4e4d789 Compare July 10, 2026 22:58
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.

2 participants