From fc4ceab247ec67c750b81334f53199b7e8178304 Mon Sep 17 00:00:00 2001 From: Joshua Temple Date: Mon, 15 Jun 2026 11:47:34 -0400 Subject: [PATCH] docs: add repo-fit and adoption section to README Signed-off-by: Joshua Temple --- README.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/README.md b/README.md index 82fc582e..6f24d3d6 100644 --- a/README.md +++ b/README.md @@ -137,6 +137,27 @@ flowchart TD --- +## Is cascade right for your repo? + +cascade earns its keep when you promote a built artifact through a chain of environments. It is a strong fit when most of these hold: + +- You deploy to **two or more environments** (say dev, test, prod) and want the *same* artifact promoted through them, never rebuilt per stage. +- You are on **GitHub Actions** and would rather own your deploy logic in reusable workflows than run a separate CD platform. +- You want **promotion gates, hotfix-to-any-environment, and rollback** without hand-wiring that state machine. +- You can adopt **conventional commits** (cascade derives versions, changelogs, and the breaking-change gate from them). + +It is likely overkill for a single environment with a plain build-and-release on push, or a repo with no deployments at all, though the no-environment mode still gives you conventional-commit versioning and releases. + +**Not trunk-based yet?** cascade promotes *from trunk*: you merge to one trunk branch and cascade promotes that line through your environments. If you run release branches or a GitFlow model today, adopting cascade means moving promotion onto a trunk-based flow. That is a deliberate shift, but cascade is a practical vehicle for it: your existing build and deploy steps become reusable-workflow callbacks, and cascade takes over the promotion, state, and release wiring on top of them. + +### What adopting looks like + +Keep the build and deploy logic you already have, wrap each as a `workflow_call` reusable workflow, describe your environments and callbacks in the manifest, and let cascade generate the orchestration. Tooling you already rely on stays yours: point cascade's changelog or release step at your own workflow, or switch it off, while cascade owns the promotion cascade. + +Start with the [Getting Started guide](https://stablekernel.github.io/cascade/getting-started/), the [Callback Contract](https://stablekernel.github.io/cascade/callback-contract/) for the inputs cascade passes your workflows, and the [hardening guide](https://stablekernel.github.io/cascade/security/hardening/) for the GitHub setup (branch protection, environments, scoped tokens) to put in place. + +--- + ## Quick start ### 1. Install the CLI