From 4e17ccf1f71b08242e1a5760b38c6fb7d53865a7 Mon Sep 17 00:00:00 2001 From: Jonathan Miller Date: Thu, 7 May 2026 14:32:11 -0500 Subject: [PATCH] docs: update cascade docs for v2 multi-branch support [skip ci] --- docs/workflows/cascade-dev.md | 49 +++++++++++++++++++---------------- 1 file changed, 26 insertions(+), 23 deletions(-) diff --git a/docs/workflows/cascade-dev.md b/docs/workflows/cascade-dev.md index 6296555..6da4a62 100644 --- a/docs/workflows/cascade-dev.md +++ b/docs/workflows/cascade-dev.md @@ -8,7 +8,7 @@ DEFGROUP: MokoStandards.Documentation INGROUP: MokoStandards.Workflows REPO: https://git.mokoconsulting.tech/MokoConsulting/MokoStandards-API PATH: /docs/workflows/cascade-dev.md -VERSION: 01.00.00 +VERSION: 02.00.00 BRIEF: Documentation for the cascade main → dev workflow --> @@ -16,7 +16,7 @@ BRIEF: Documentation for the cascade main → dev workflow # Cascade Main → Dev Workflow -**Status**: ✅ Active | **Version**: 01.00.00 | **Last Updated**: 2026-05-07 +**Status**: ✅ Active | **Version**: 02.00.00 | **Last Updated**: 2026-05-07 ## Table of Contents @@ -34,11 +34,11 @@ BRIEF: Documentation for the cascade main → dev workflow ## Overview -The **Cascade Main → Dev** workflow automatically forward-merges `main` into `dev` after every push to `main`. This keeps the `dev` branch in sync with stable releases without manual intervention. +The **Cascade Main → Dev** workflow automatically forward-merges `main` into all open branches (`dev`, `rc/*`, `beta/*`, `alpha/*`) after every push to `main`. This keeps all development and pre-release branches in sync with stable releases without manual intervention. ### Purpose -- **Sync**: Ensure `dev` always includes the latest stable code from `main` +- **Sync**: Ensure all open branches (`dev`, `rc/*`, `beta/*`, `alpha/*`) always include the latest stable code from `main` - **Automation**: Eliminate manual merge-forward after releases - **Conflict Detection**: Surface merge conflicts early via auto-created PRs - **Safety**: Never force-pushes or overwrites — creates PRs for manual resolution when needed @@ -58,22 +58,24 @@ The **Cascade Main → Dev** workflow automatically forward-merges `main` into ` ``` Push to main ↓ -Check if dev branch exists - ↓ (skip if no dev branch) -Compare main vs dev (commits ahead) - ↓ (skip if already in sync) -Create PR (main → dev) - ↓ (reuse existing if one is open) -Check mergeable - ├─ Clean → Auto-merge PR ✅ - └─ Conflicts → Leave PR open for manual resolution ⚠️ +Discover target branches (dev, dev/*, rc/*, beta/*, alpha/*) + ↓ (skip if none found) +For each target branch: + ↓ + Compare main vs branch (commits ahead) + ↓ (skip if already in sync) + Create PR (main → branch) + ↓ (reuse existing if one is open) + Check mergeable + ├─ Clean → Auto-merge PR ✅ + └─ Conflicts → Leave PR open for manual resolution ⚠️ ``` ### Step-by-Step -1. **Branch Check**: Queries `GET /repos/{owner}/{repo}/branches/dev` — if 404, the workflow exits cleanly -2. **Diff Check**: Queries `GET /repos/{owner}/{repo}/compare/dev...main` — if `total_commits` is 0, dev is already in sync -3. **PR Creation**: Creates a PR via `POST /repos/{owner}/{repo}/pulls` with `head: main`, `base: dev` +1. **Branch Discovery**: Queries all branches via paginated API, filters to targets matching `dev`, `dev/*`, `rc/*`, `beta/*`, `alpha/*` +2. **Diff Check**: For each target, queries `GET /repos/{owner}/{repo}/compare/{branch}...main` — if `total_commits` is 0, the branch is already in sync +3. **PR Creation**: Creates a PR via `POST /repos/{owner}/{repo}/pulls` with `head: main`, `base: {branch}` 4. **Duplicate Prevention**: Before creating, checks for existing open PRs with the same head/base 5. **Auto-Merge**: If `mergeable: true`, merges via `POST /repos/{owner}/{repo}/pulls/{index}/merge` with merge style 6. **Conflict Handling**: If `mergeable: false`, the PR stays open with a clear description for manual resolution @@ -121,7 +123,7 @@ Runs on `ubuntu-latest` — no special runner requirements. When the auto-merge detects conflicts: -1. The workflow creates (or reuses) a PR titled `chore: cascade main → dev ({sha}) [skip ci]` +1. The workflow creates (or reuses) a PR titled `chore: cascade main → {branch} ({sha}) [skip ci]` 2. The PR body explains the conflict and links to the workflow 3. The workflow exits successfully (not a failure — conflicts are expected) 4. A developer must: @@ -169,7 +171,7 @@ The workflow file `.gitea/workflows/cascade-dev.yml` is deployed to all governed The cascade workflow is automatically deployed by the bulk sync process. To manually add: 1. Copy `.gitea/workflows/cascade-dev.yml` from any governed repo -2. Ensure the repo has a `dev` branch +2. Ensure the repo has at least one target branch (`dev`, `rc/*`, `beta/*`, or `alpha/*`) 3. Ensure `GA_TOKEN` secret is configured --- @@ -191,17 +193,17 @@ The cascade workflow is automatically deployed by the bulk sync process. To manu **Symptom**: PR created but left open -**Cause**: Merge conflicts between `main` and `dev` +**Cause**: Merge conflicts between `main` and the target branch **Solution**: Resolve conflicts locally and merge the PR manually -### "No dev branch found" Message +### "No cascade target branches found" Message -**Symptom**: Workflow logs show "No dev branch found — skipping cascade" +**Symptom**: Workflow logs show "No cascade target branches found" -**Cause**: Repository doesn't have a `dev` branch +**Cause**: Repository doesn't have any target branches (`dev`, `rc/*`, `beta/*`, `alpha/*`) -**Solution**: Create dev branch from main: `git checkout -b dev main && git push origin dev` +**Solution**: Create a target branch from main: `git checkout -b dev main && git push origin dev` --- @@ -217,3 +219,4 @@ The cascade workflow is automatically deployed by the bulk sync process. To manu | Version | Date | Changes | |---------|------|---------| | 01.00.00 | 2026-05-07 | Initial release — PR-based merge with conflict detection | +| 02.00.00 | 2026-05-07 | Cascade to all open branches (dev, rc/*, beta/*, alpha/*), not just dev |