diff --git a/docs/branching.md b/docs/branching.md index 06ed06133..d5856a977 100644 --- a/docs/branching.md +++ b/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) @@ -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.