From 0cb4ece382abe4e83f9e787e36c729d12d9c564f Mon Sep 17 00:00:00 2001
From: Jonathan Miller <1+jmiller@noreply.git.mokoconsulting.tech>
Date: Sat, 30 May 2026 14:59:52 +0000
Subject: [PATCH] chore: sync CONTRIBUTING.md from moko-platform [skip ci]

---
 CONTRIBUTING.md | 24 ++++++++++++++++++++++--
 1 file changed, 22 insertions(+), 2 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index ea9a5fc3e9..c0b4858bfe 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -88,13 +88,33 @@ Each branch appends a suffix to indicate stability:
 
 ### Auto version bump
 
-On every push to `dev`, `alpha`, `beta`, `rc`, or `feature/*`:
+On every push to `dev`, `feature/*`, or `patch/*`:
 
 1. Patch version incremented
-2. Stability suffix applied based on branch name
+2. Stability suffix `-dev` applied
 3. All version-bearing files updated (manifests, CHANGELOG, PHP headers, etc.)
 4. Commit created with `[skip ci]` to avoid loops
 
+### Release version flow
+
+Version bumps happen at specific release events:
+
+| Event | Bump | Example |
+|-------|------|---------|
+| Feature merged to dev | Patch bump after dev release | `02.09.01-dev` → release → `02.09.02-dev` |
+| Dev promoted to RC | Minor bump | `02.09.02-dev` → `02.10.00-rc` |
+| RC merged to main | Minor bump | `02.10.00-rc` → `02.11.00` (stable) |
+| Dev recreated from main | Patch bump | `02.11.00` → `02.11.01-dev` |
+
+### Release stream copies
+
+When a higher-stability release is published, copies are created for all lesser streams with the same base version:
+
+- **RC `02.10.00-rc`** also creates: `02.10.00-dev`, `02.10.00-alpha`, `02.10.00-beta`
+- **Stable `02.11.00`** also creates: `02.11.00-dev`, `02.11.00-alpha`, `02.11.00-beta`, `02.11.00-rc`
+
+This ensures Joomla sites on ANY stability channel see the update (Joomla only shows versions higher than what's installed).
+
 ### Version files
 
 The version tools update all files containing version stamps: