Effective Branching Strategy for Optima¶

Overview¶

This document outlines a comprehensive and effective branching strategy for managing the Optima GitHub repository. The strategy is designed to streamline the development process, enhance collaboration, and maintain a clean, organized repository.

Branch Types¶

1. `main` Branch¶

Purpose: Represents the official release history.
Usage: Only updated through merged release branches. Direct commits are prohibited.
Protection: Protected branch with restrictions on who can merge.

2. `develop` Branch¶

Purpose: Serves as an integration branch for features; reflects the latest delivered development changes.
Usage: All completed features are merged here.
Protection: Protected branch requiring pull request reviews before merging.
Deployment: Automatically deployed to Test environment.

3. `qa` Branch¶

Purpose: Pre-release branch for QA testing.
Usage: Stabilization and testing before production release.
Protection: Protected branch requiring pull request reviews before merging.
Deployment: Automatically deployed to Dev environment.

4. `feature` Branches¶

Naming Convention: feature/<issue-number>-<feature-name>
Purpose: Used for developing new features or enhancements.
Usage:
Branched off from develop.
Merged back into develop upon completion.
Examples:
feature/45-user-authentication
feature/78-improve-dashboard-ui

5. `release` Branches¶

Naming Convention: release/<version-number>
Purpose: Supports preparation of a new production release.
Usage:
Created from qa after QA approval.
Merged into main and back into develop and qa after release.
Examples:
release/2.1.0

6. `hotfix` Branches¶

Naming Convention: hotfix/<issue-number>-<hotfix-name>
Purpose: For critical fixes to the production code.
Usage:
Branched from main.
Merged into both main,develop and qa after completion.
Examples:
hotfix/101-fix-login-bug

Workflow¶

1. Feature Development¶

Create a Feature Branch:

git checkout -b feature/<issue-number>-<feature-name> develop

Based on the develop branch.
Include the issue number for tracking.
Develop and Commit Changes:
Make atomic and logical commits with clear messages.
Regularly commit changes to avoid large diffs.
Regularly Rebase with develop:

git fetch  

git rebase develop

Keep the feature branch up-to-date and resolve conflicts early.
Open a Pull Request:
Provide a detailed description of changes.
Link to the relevant issue(s).
Code Review and Merge:
Address feedback from code reviews.
Once approved, squash and merge into develop.
Delete the Feature Branch:

git branch -d feature/<issue-number>-<feature-name>  

git push origin --delete feature/<issue-number>-<feature-name>

2. QA Testing¶

Promote Code to qa Branch:
- When develop is stable, merge into qa:
```
git checkout qa  
git merge --no-ff develop 
```
- Alternatively, create a pull request from develop to qa.
- Changes are deployed to the Dev environment for QA testing.
QA Testing in Dev Environment:
- QA team tests the code.
- Any bugs found are fixed in develop.
- Process repeats until QA approves.

3. Release Preparation¶

Create a Release Branch:

git checkout -b release/<version-number> qa

Start release preparations from qa.
Update version numbers and documentation.
Stabilize the Release Branch:
Fix bugs and make final adjustments.
Only critical changes are allowed.
Merge into main and Tag:

git checkout main  

git merge --no-ff release/<version-number>  

git tag -a v<version-number> -m "Release version <version-number>"

Merge Back into develop and qa:

git checkout develop  

git merge --no-ff main  


git checkout qa  

git merge --no-ff main

Delete the Release Branch:

git branch -d release/<version-number>  

git push origin --delete release/<version-number>

4. Hotfix Process¶

Identify Critical Issue:
An urgent bug is discovered in main.
Create a Hotfix Branch:

git checkout -b hotfix/<issue-number>-<hotfix-name> main

Apply the Fix:
Make necessary changes and commit with a clear message.
Merge into main and Tag:

git checkout main  

git merge --no-ff hotfix/<issue-number>-<hotfix-name>  

git tag -a v<version-number> -m "Hotfix version <version-number>"

Merge into develop and qa:

git checkout develop  

git merge --no-ff hotfix/<issue-number>-<hotfix-name>  

git checkout qa  

git merge --no-ff hotfix/<issue-number>-<hotfix-name>

Delete the Hotfix Branch:

git branch -d hotfix/<issue-number>-<hotfix-name>  

git push origin --delete hotfix/<issue-number>-<hotfix-name>

Merge Strategies¶

Feature Branches to develop:
Use squash merging to condense all commits into one.
Merging develop into qa:
Use no-fast-forward (--no-ff) merges to preserve history.
Release and Hotfix Branches:
Use no-fast-forward (--no-ff) merges into main,develop,qa
Pull Requests:
Required for all merges into develop, qa, release and main.
Ensure that all status checks pass before merging.

Deployment Automation¶

Test Environment¶

Trigger: Commits to develop.
Action: Automatically deploy latest develop to Test environment.

Dev Environment¶

Trigger: Commits to qa.
Action: Automatically deploy latest qa to Dev environment.

Production Environment¶

Trigger: A pipeline executed by deveops team during CR window only
Action: Deploy main to Production environment duing CR window.

Naming Conventions¶

Branch Names:
Use lowercase letters, numbers, and hyphens (-).
Format: <type>/<issue-number>-<description>
Clearly describe the purpose of the branch.
Commit Messages:
Use imperative mood.
Include issue numbers (e.g., Fix login bug (#101)).
Tags:
Follow versioning format: v<major>.<minor>.<patch>
Example: v2.1.0

Best Practices¶

1. Regularly Pull Changes¶

Sync your branch with develop to incorporate the latest changes:

git fetch origin  

git rebase origin/develop

2. Code Reviews¶

Peer Review:
All code must be reviewed by at least one other team member.
Review Criteria:
Coding standards compliance.
Functionality correctness.
Test coverage.
Documentation completeness.

3. Commit Messages¶

Format:

<type>(<scope>): <subject>  

[Optional body]  

[Optional footer(s)]

Types: feat, fix, docs, style, refactor, test, chore.
Scope: The section of the codebase affected.
Subject: Brief description of the change.
Example:

feat(auth): add user login functionality  

Implemented OAuth2 authentication for user login.  

Fixes #45

4. Pull Request Guidelines¶

Description:
Summarize changes and why they're necessary.
Testing Instructions:
Provide steps for reviewers to test the changes.
Checklists:
Ensure all items are addressed before requesting review.

5. Testing Before Merging¶

Unit Tests:
Write tests for new code.
Ensure coverage thresholds are met.
Integration Tests:
Test interactions between components.
Continuous Integration:
All tests must pass in the CI pipeline.

6. Branch Protection Rules¶

Protected Branches:
main and develop are protected.
Requirements:
Pull request review.
Passing status checks.
Up-to-date with base branch before merging.
Restrictions:
Limit who can push or merge to these branches.

7. Automated Testing¶

CI Tools:
Utilize tools like GitHub Actions, Jenkins, or Travis CI.
Automation:
Automated builds and tests on commits and pull requests.
Notifications:
Alerts on build failures or test regressions.

8. Code Ownership¶

Define Ownership:
Assign code owners for different modules or components.
Reviewers:
Code owners are automatically requested as reviewers.
Accountability:
Ensures responsibility and code quality.

Versioning and Release Management¶

Semantic Versioning:
Format: MAJOR.MINOR.PATCH
- MAJOR: Incompatible API changes.
- MINOR: Backwards-compatible functionality.
- PATCH: Backwards-compatible bug fixes.
Release Notes:
Document changes, new features, and bug fixes.
Tagging Releases:

Use annotated tags with a message.

git tag -a v2.1.0 -m "Release version 2.1.0"

Continuous Integration/Continuous Deployment (CI/CD)¶

CI Pipeline:
Automatically build and test on every push and pull request.
CD Pipeline:
Deploy develop to staging environment.
Deploy main to production environment.