# 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<major.minor>` (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`.