MokoConsulting/MokoCLI
Public Access
1
0
Fork 0
Code Issues 3 Pull Requests 2 Packages Releases 8 Wiki Activity

docs: update cascade docs for v2 multi-branch support [skip ci]

Browse Source
This commit is contained in:
Jonathan Miller
2026-05-07 14:32:11 -05:00
parent 5d6d9536a2
commit 4e17ccf1f7
1 changed files with 26 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/workflows/cascade-dev.md
+26 -23
View File
@@ -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 |