alexeiidonetskiy · August 26, 2025 13:24 · Aug 26, 2025
diff --git a/README.md b/README.md
@@ -0,0 +1,150 @@
+```mermaid
+---
+config:
+  theme: mc
+---
+gitGraph
+    commit id: "commits"
+    checkout main
+    commit id: "v1.11.0 PROD"
+    branch release/1.12.0
+    checkout release/1.12.0
+    commit id: "start 1.12.0 DEV"
+    branch feature/MTO-001
+    checkout feature/MTO-001
+    commit id: "MTO-001 work"
+    commit id: "MTO-001 done"
+    checkout release/1.12.0
+    merge feature/MTO-001
+    branch feature/MTO-002
+    checkout feature/MTO-002
+    commit id: "MTO-002 work"
+    commit id: "MTO-002 done"
+    checkout release/1.12.0
+    merge feature/MTO-002
+    checkout main
+    merge release/1.12.0 tag: "v1.12.0 PROD"
+    branch release/1.13.0
+    checkout release/1.13.0
+    commit id: "start 1.13.0 DEV"
+    merge release/1.12.0 id: "forward merge"
+    branch hotfix/MTO-003
+    checkout hotfix/MTO-003
+    commit id: "hotfix bug"
+    checkout main
+    merge hotfix/MTO-003 id: "hotfix to main"
+    checkout release/1.13.0
+    merge hotfix/MTO-003 id: "hotfix forward"
+    checkout main
+    merge release/1.13.0 tag: "v1.13.0 PROD"
+
+```
+
+# Git Flow Instructions (GitLab)
+
+## 1. Branch Types
+
+* **`main`** → Always production-ready, protected branch in GitLab.
+* **`release/X.Y.Z`** → One per planned release. Deployed to **DEV** for testing.
+* **`feature/MTO-###`** → Feature branches created from the active release branch.
+* **`hotfix/MTO-###`** → Urgent bugfix branches from `main`.
+
+## 2. Starting a New Release
+
+1. From `main`, create the new release branch:
+
+```bash
+git checkout main
+git pull
+git checkout -b release/X.Y.Z
+git push -u origin release/X.Y.Z
+```
+
+2. Deploy `release/X.Y.Z` to **DEV**.
+3. Protect the release branch in GitLab to avoid accidental deletion.
+
+## 3. Developing Features
+
+1. Create your feature branch from the active release branch:
+
+```bash
+git checkout release/X.Y.Z
+git pull
+git checkout -b feature/MTO-123
+```
+
+2. When done, squash commits locally if needed and create a **Merge Request** in GitLab targeting the release branch.
+3. Merge the MR using GitLab’s merge interface, **do not squash merge release → release merges**.
+4. Delete the feature branch after merge.
+
+## 4. Testing a Release in DEV
+
+* All merged features in `release/X.Y.Z` are deployed to DEV.
+* QA tests against DEV.
+* If bugs are found → fix them **directly in the release branch**.
+
+## 5. Releasing to Production
+
+1. Merge the tested release into `main` using a **Merge Request**:
+
+```bash
+git checkout main
+git pull
+git merge --no-ff release/X.Y.Z
+git tag vX.Y.Z
+git push origin main --tags
+```
+
+2. Deploy `main` to PROD.
+3. Protect `main` in GitLab to enforce PRs for all merges.
+
+## 6. Creating the Next Release
+
+1. From `main`, create the next release branch:
+
+```bash
+git checkout main
+git pull
+git checkout -b release/X.Y+1.Z
+git push -u origin release/X.Y+1.Z
+```
+
+2. Forward-merge changes from the previous release if needed:
+
+```bash
+git checkout release/X.Y+1.Z
+git merge release/X.Y.Z
+git push
+```
+
+## 7. Hotfixes
+
+1. Create a hotfix from `main`:
+
+```bash
+git checkout main
+git pull
+git checkout -b hotfix/MTO-456
+```
+
+2. After fix:
+
+```bash
+git checkout main
+git merge --no-ff hotfix/MTO-456
+git tag vX.Y.Z+1
+git push origin main --tags
+
+# Forward hotfix into active release branch
+git checkout release/X.Y.Z
+git merge --no-ff hotfix/MTO-456
+git push
+```
+
+## 8. Rules & Constraints
+
+* **Never delete a release branch** until all future releases include its changes.
+* **Do not squash merge release → release** merges — keep them linear.
+* **Squash merge feature → release** merges if you want cleaner history.
+* Always merge forward from older → newer release branches before new work.
+* Use GitLab branch protection to enforce workflow rules on `main` and `release/*` branches.