Skip to content

docs: clarify cascade splits build and deploy into separate stages#249

Merged
joshua-temple merged 1 commit into
mainfrom
docs/adoption-stage-decomposition
Jun 22, 2026
Merged

docs: clarify cascade splits build and deploy into separate stages#249
joshua-temple merged 1 commit into
mainfrom
docs/adoption-stage-decomposition

Conversation

@joshua-temple

Copy link
Copy Markdown
Collaborator

Problem

The migration guidance reads "keep your build and deploy logic, just wrap each as a reusable workflow," which assumes build and deploy are already separate. The common starting point is the opposite: one workflow or job that builds and deploys in a single pass, often rebuilding per environment. The docs never explain that this coupling is incompatible with cascade.

Fix

  • adoption.md: add an "If your build and deploy are one workflow" subsection in the migration area explaining that cascade runs discrete stages (validate, build, deploy, optionally publish), each its own workflow_call workflow, and why the split is required: cascade builds once at orchestrate and promotes the same SHA-pinned artifact across environments, running only deploy at later envs. Includes concrete split steps and a pointer from the migration table.
  • comparison.md: one clarifying clause in the "You own the deploy logic" bullet noting a fused pipeline gets split into build and deploy callbacks on adoption.

Verification

  • Docs-only change.
  • Independent review: APPROVE. Build-once/SHA-pinned promotion, output chaining via depends_on, and the env gate living in the deploy workflow all verified against the code. Anchors and cross-page links checked.

Signed-off-by: Joshua Temple <joshua.temple@stablekernel.com>
@joshua-temple joshua-temple enabled auto-merge (squash) June 22, 2026 17:22
@joshua-temple joshua-temple merged commit 8bc19a0 into main Jun 22, 2026
15 checks passed
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