diff --git a/BRANCHING.md b/BRANCHING.md new file mode 100644 index 000000000..ab0aaee04 --- /dev/null +++ b/BRANCHING.md @@ -0,0 +1,58 @@ +# Branching Strategy + +BMad uses a **stable-branch** model: `main` is the development branch, and numbered branches hold stable releases that receive only cherry-picked fixes. + +``` +main ●───●───●───●───●───●───●───●──────► 7.0, ... + \ \ +v6 ●───●───● \ patches only + │ │ │ \ + v6.0.0 v6.0.2 \ + │ \ + v6.0.1 \ + \ +v6.1 ●───●───● patches only + │ │ + v6.1.0 v6.1.1 +``` + +Every minor version (6.0, 6.1, ...) ships from `main` as its own stable branch. Only patches are cherry-picked onto stable branches. + +This pattern is used by Node.js, Go, and Python — adapted here for a project that ships an npm CLI. + +--- + +## The Three Lanes + +| Branch | Purpose | What goes here | Gets tagged? | +| --- | --- | --- | --- | +| `main` | Next version development | All new work, via PRs | Pre-release only (`X.Y.0-alpha.N`) | +| `v` (e.g., `v6`, `v6.1`) | Stable release maintenance | Cherry-picks from `main` only | Yes — `vX.Y.Z` | +| Forks | Experimental work | Anything | Never | + +### Rules + +1. **All fixes must land on `main` first**, then get cherry-picked to the stable branch. +2. **One stable branch at a time.** When a new major version ships, the old one stops receiving patches. + +--- + +## Lifecycle + +**New version:** Feature branches target `main` (see [CONTRIBUTING.md](CONTRIBUTING.md)). Pre-release tags cut from `main` as needed. + +**Stable release:** When ready, cut a stable branch from `main` (e.g., `v6`, `v6.1`), tag it, bump `main` to the next version. From that point, `main` is the next release. + +**Patch:** Fix lands on `main` via normal PR. Cherry-pick the merged commit to the stable branch. Tag the patch release. + +**Retirement:** When the next major ships, the old stable branch is left as-is. Tags remain as permanent references. + +--- + +## FAQ + +**Why not Git Flow?** +Git Flow adds a `develop` branch and release branches per version. For one active version and a small team, that's overhead without benefit. + +**Why cherry-pick instead of merging `main` into stable?** +Cherry-picking isolates fixes; merging would pull incomplete features from `main`. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 06ab6d174..68cb447f6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -73,7 +73,7 @@ After searching, use the [feature request template](https://github.com/bmad-code ### Target Branch -Submit PRs to the `main` branch. +Submit PRs to the `main` branch unless you are patching a stable release branch. See [BRANCHING.md](BRANCHING.md) for details on the stable-branch model. ### PR Size