From 325dbc10a87e07312fdfd224d225764bb96e120a Mon Sep 17 00:00:00 2001 From: Joshua Temple Date: Mon, 22 Jun 2026 11:55:44 -0400 Subject: [PATCH] docs: make release-only a first-class adoption path Signed-off-by: Joshua Temple --- docs/src/content/docs/adoption.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/src/content/docs/adoption.md b/docs/src/content/docs/adoption.md index b285ee6..2c43feb 100644 --- a/docs/src/content/docs/adoption.md +++ b/docs/src/content/docs/adoption.md @@ -13,11 +13,13 @@ You own **the verbs**. Build, deploy, validate, and publish are *your* logic, su The flow in one line: you write a manifest plus callback workflows, run `cascade generate-workflow`, and commit the generated orchestration workflows into your repository. From then on, GitHub Actions runs them: cascade orchestrates on merge, promotes between environments, and releases at the terminal environment. +cascade fits two shapes equally. A **deploy-through-environments** pipeline promotes a commit across one or more environments and releases at the end. A **release-only** repo deploys nowhere and just ships versioned releases; you omit `environments` and still get conventional-commit version derivation, changelog, and release management. Both are first-class. The rest of this guide covers the environment-promotion path in full and calls out where release-only repos diverge. + ## Prerequisites - **GitHub Actions enabled** on the repository, with trunk-based development (a single primary branch). - **Conventional Commits - required.** cascade derives the semver bump, the changelog, and breaking-change detection entirely from Conventional Commit messages. This is not optional. Commits that do not follow the convention are not processed correctly and version derivation can fail. See [Versioning and schema compatibility](/cascade/versioning/). -- **GitHub setup**: environments for each deploy stage, branch and tag protection, the secrets your callbacks consume, and scoped tokens. The [Security and Hardening](/cascade/security/hardening/) checklist is the authoritative list; wire it up before your first production promotion. +- **GitHub setup**: branch and tag protection, the secrets your callbacks consume, and scoped tokens. If you deploy, also configure a GitHub environment for each deploy stage; a release-only repo has no environments to set up and skips that part. The [Security and Hardening](/cascade/security/hardening/) checklist is the authoritative list; wire it up before your first production release. - The `cascade` CLI for local generation (Go 1.25+ to `go install`; in Actions, the setup action installs it for you). See [Getting Started](/cascade/getting-started/). ## Build a pipeline from scratch @@ -41,6 +43,8 @@ Environments are **positional**, not named by meaning. cascade attaches no seman So `environments: [dev, test, prod]` means dev is first, test is the prerelease stage, and prod is the release stage. The names are yours to choose; only the order carries meaning. See the [Manifest Reference](/cascade/configuration/) for the full structural rules, including zero-environment (release-only) mode. +**Release-only repos:** if you ship releases without deploying anywhere, omit `environments` entirely and skip straight to releases. The breaking-change gate and publish boundary still apply at the release; you just have no environments to promote across. Scaffold this shape with `cascade init --topology no-env`, and see [No-env (release-only)](#topologies) below. + ### 2. Write a minimal manifest A three-environment manifest with one build, one deploy, optional validation, and an optional publish callback: @@ -187,7 +191,7 @@ The full, ordered checklist is in [Security and Hardening](/cascade/security/har Environment count is structural. Pick the shape that matches your project: -- **No-env (release-only)** - omit `environments`. For libraries and CLIs that publish releases without deploying anywhere. +- **No-env (release-only)** - omit `environments`; scaffold with `cascade init --topology no-env`. The fit for any repo that ships versioned releases without deploying anywhere: libraries, CLIs, SDKs, published container images, and schemas or packages consumed by other repos. You still get conventional-commit version derivation, changelog, and release management. Hotfix and rollback need two or more environments, so they do not apply here. - **2-env** - `dev` + `prod`. Smallest promotion chain with a prerelease stage. - **3-env** - `dev` + `staging` + `prod` (or `pre` + `staging` + `prod`). The common default. - **4-env** - `dev` + `staging` + `pre` + `prod`. Adds a dedicated prerelease stage before production.