Merge pull request #1937 from tisnik/lcore-1645

LCORE-1645: Contribution and branching documentation

Author: tisnik

docs/branching.md

@@ -12,8 +12,15 @@
 * [Branches naming](#branches-naming)
 * [Branching visualization](#branching-visualization)
     * [Feature and fix branches that are merged into the main branch](#feature-and-fix-branches-that-are-merged-into-the-main-branch)
-    * [Cherry picking changes into release (stable) branch from the main branch](#cherry-picking-changes-into-release-stable-branch-from-the-main-branch)
+    * [Cherry-picking changes into release (stable) branch from the main branch](#cherry-picking-changes-into-release-stable-branch-from-the-main-branch)
     * [Multiple release branches, fixes made in fix branches](#multiple-release-branches-fixes-made-in-fix-branches)
+* [Branching strategy](#branching-strategy)
+    * [Steps (ordered)](#steps-ordered)
+    * [Visualized flow](#visualized-flow)
+    * [Cherry picking](#cherry-picking)
+* [Git workflow](#git-workflow)
+    * [New release branch](#new-release-branch)
+    * [Update/fix existing release branch](#updatefix-existing-release-branch)
 
 <!-- vim-markdown-toc -->
 
@@ -160,3 +167,150 @@ branch naming conventions are not covered here.
 
 [branching_3](https://lightspeed-core.github.io/lightspeed-stack/branching_3.svg)
 
+
+## Branching strategy
+
+### Steps (ordered)
+
+1. Create release branch
+
+2. Update metadata, such us version etc.
+
+3. Run CI: full test suite, linters, build (this is to check that branching is
+   ok)
+
+4. Stabilize: apply bug fixes, adjust configurations, small polish commits on
+   release branch
+
+5. QA / UAT: Deploy release branch to staging environment (Konflux)
+
+6. Fix issues: commit fixes directly on release branch; re-run CI
+
+7. Prepare release: Finalize changelog, update docs, set release notes
+
+8. Deploy: trigger production deployment (Konflux)
+
+9. Hotfixes (if needed): create hotfix/x.y.z+1 from main, then follow same flow
+
+
+
+### Visualized flow
+
+```
+                 +-----------------+
+                 |   main branch   |
+                 |                 |
+                 +--------+--------+
+                          | 
+                          |  create release/x.y.z
+                          v 
+                 +-----------------+
+                 |  release/x.y.z  |
+                 |  (stabilize)    |
+                 +----+---+---+----+
+                      |   |   |
+     update changelog |   |   | bug fixes & CI
+                      |   |   |
+                      v   v   v
+                 +-----------------+
+                 | Run CI / Tests  |
+                 +--------+--------+
+                          | 
+                          v 
+                 +-----------------+
+                 |  Run e2e tests  |
+                 |  in Konflux     |
+                 |                 |
+                 +--------+--------+
+                          |
+            issues found  |  validated
+                 +--------+-----------+
+                 |                    |
+                 v                    v
+       +----------------+     +----------------+
+       | Fix on release |     | Ready for ship |
+       +-------+--------+     +-------+--------+
+               |                      |
+               v                      v
+          (re-run CI)          tag the release
+               |                      |
+               v                      v
+       +----------------+     +----------------+
+       |  return to QA  |     |    (tag vX)    |------------+
+       +----------------+     +----------------+            |
+                                      |                     |
+                                      v                     v
+                              +----------------+    +-----------------+
+                              |  Build images  |    | Publish on PyPi |
+                              +----------------+    +-----------------+
+```
+
+
+
+### Cherry picking
+
+Cherry-picking is a Git operation that applies the changes introduced by a
+specific commit from one branch onto another branch without merging the entire
+branch history. Key points:
+
+* Purpose: move a single fix, feature, or change (identified by its commit SHA)
+  from one line of development (e.g., from main branch) into another (in our
+  case into a release branch) when you don’t want to merge all other commits.
+
+* How it works: Git copies the patch (diff) from the selected commit, attempts
+  to apply it to the current branch, and creates a new commit with a new SHA on
+  that branch.
+
+* Typical workflow:
+   - Checkout the target branch (e.g., release/0.6.0).
+   - Run `git cherry-pick` (or multiple SHAs).
+   - Resolve any merge conflicts, then `git add` and `git cherry-pick --continue`.
+   Test, review, and push the resulting commit into the release branch.
+
+NOTE: the cherry picking can be made in main -> release branch direction or
+vice versa. We prefer the first method when possible.
+
+
+
+## Git workflow
+
+### New release branch
+
+```bash
+# 1. Create release branch from the main branch
+git checkout -b release/1.2.0 main
+
+# 2. Update version number in build files
+
+# 3. Commit and push
+git commit -am "Prepare for 1.2.0 release"
+git push origin release/1.2.0
+
+# 4. Tag the release
+git tag -a v1.2.0 -m "Release 1.2.0"
+git push origin v1.2.0
+
+# 5. Merge into main (optional step)
+git checkout main && git merge release/1.2.0
+```
+
+
+
+### Update/fix existing release branch
+
+```bash
+# 1. Create branch from the release branch
+git checkout -b release/1.2.1 release/1.2.0
+
+# 2. Update version number in build files
+
+# 3. Commit and push
+git commit -am "Prepare for 1.2.1 fix"
+git push origin release/1.2.1
+
+# 4. Tag the release
+git tag -a v1.2.1 -m "Release 1.2.1"
+git push origin v1.2.1
+```
+
+NOTE: 1.2.0 and 1.2.1 are just examples, of course.