doc-development-workflow/docs/02-version-control/01-gitflow.md

id, title

id	title
02-gitflow	Gitflow

Gitflow is a branching strategy for Git that defines how to organize, develop, and release code in a structured way.

It provides a clear framework for:

• Branch creation → where new features, fixes, or releases should start.
• Branch merging → how and when to integrate changes.
• Release management → preparing stable builds before deployment.
• Hotfix handling → quickly addressing urgent issues in production.

By separating ongoing development from production-ready code, Gitflow ensures:

• Smooth parallel development across teams.
• Stable and reliable production releases.
• A transparent and predictable release cycle.
• A fast response to urgent production incidents.

---

Branches

1️⃣ Master Branch

The master branch represents the LIVE environment. It always contains the latest stable code that has been fully tested and approved for deployment.

• Any changes to the master branch must go through a pull request.
• Team Leaders are responsible for reviewing and merging approved changes.

This ensures the master branch remains a single source of truth for the production system.

---
    config:
        theme: 'base'
        gitGraph:
            mainBranchName: 'master'
            showCommitLabel: false
---
    gitGraph
        commit
        commit
        branch release
        commit
        commit
        commit tag: "v1 (SAT)"
        checkout master
        merge release tag: "LIVE v1"
        checkout release
        commit
        commit
        commit
        commit tag: "v2 (SAT)"
        checkout master
        merge release tag: "LIVE v2"

2️⃣ Release Branch

The release branch serves as the staging ground for production-ready code. It contains all features and fixes that have passed internal testing and are being prepared for deployment.

• A SAT¹ version will be created from the release branch and tagged with a version number.
• Once the SAT build is approved and deployed to LIVE, the confirmed version will be merged into the master branch.
• Any changes to the master branch must go through a pull request.
• Team Leaders are responsible for reviewing and merging approved changes.

This workflow ensures that only validated and stable code reaches production.

---
    config:
        theme: 'base'
        gitGraph:
            mainBranchName: 'master'
            showCommitLabel: false
---
    gitGraph
        commit
        commit
        branch release
        branch develop
        commit
        commit
        checkout release
        merge develop tag: "v1 (SAT)"
        checkout master
        merge release tag: "LIVE v1"
        checkout develop
        commit
        commit
        checkout release
        merge develop tag: "v2 (SAT)"
        checkout master
        merge release tag: "LIVE v2"

3️⃣ Develop Branch

The develop branch is the main integration branch where all features, enhancements, and bug fixes are combined. It contains the complete history of the project’s ongoing development.

• Feature branches and bugfix branches must be merged into develop through pull requests.
• Team Leaders are responsible for reviewing and approving merges.
• Once development is stable and ready for validation, develop is merged into the release branch, where a SAT version will be created and tagged.

This workflow ensures that develop is always the latest working version, but not necessarily production-ready.

---
    config:
        theme: 'base'
        gitGraph:
            mainBranchName: 'master'
            showCommitLabel: false
---
gitGraph
    commit
    commit
    branch release
    branch develop
    commit
    commit
    checkout release
    merge develop tag: "v1 (SAT)"
    checkout master
    merge release tag: "LIVE v1"
    checkout develop
    commit 
    commit 
    checkout release
    merge develop tag: "v2 (SAT)"
    checkout master
    merge release tag: "LIVE v2"
    checkout develop
    commit 

4️⃣ Feature branches

Feature branches are used to develop new functionality in isolation from the main integration and production branches. This ensures stability and prevents incomplete features from affecting the project’s main workflow.

• Each new feature must be developed in its own branch.
• Feature branches are always created from the latest develop branch.
• Once complete, the feature must be merged back into develop via a pull request.
• Team Leaders are responsible for reviewing and approving feature branch merges.
• Feature branches must never interact directly with the master branch or the release branch.

---
    config:
        theme: 'base'
        gitGraph:
            mainBranchName: 'release'
            showCommitLabel: false
---
    gitGraph
        commit
        branch develop
        commit
        branch feature/feature-a
        commit
        commit
        checkout develop
        merge feature/feature-a
        checkout release
        merge develop tag: "v1 (SAT)"
        checkout develop
        branch feature/feature-b
        commit
        commit
        checkout develop
        branch feature/feature-c
        commit
        commit
        checkout develop
        merge feature/feature-c
        checkout release
        merge develop tag: "v2 (SAT)"
        checkout develop

5️⃣ Bugfix branches

Bugfix branches are used to quickly patch issues identified before deployment to LIVE, typically during SAT. They work similarly to feature branches but are intended for urgent fixes rather than planned development.

• Bugfix branches are always created from the release branch.
• Once the fix is complete and tested, it must be merged back into release via a pull request.
• The bugfix must also be back-merged into develop to keep branches consistent.
• Team Leaders are responsible for reviewing and approving the changes.
• Bugfix branches must never interact directly with the master branch.

---
    config:
        theme: 'base'
        gitGraph:
            mainBranchName: 'release'
            showCommitLabel: false
---
    gitGraph
        commit
        branch develop
        commit
        checkout release
        merge develop tag: "v1 (SAT)"
        branch bugfix/fix-bug-a
        commit
        commit
        checkout release
        merge bugfix/fix-bug-a tag: "v2 (SAT)"
        checkout develop
        merge bugfix/fix-bug-a
        checkout release
        branch bugfix/fix-bug-b
        commit
        commit
        checkout release
        merge bugfix/fix-bug-b tag: "v3 (SAT)"
        checkout develop
        merge bugfix/fix-bug-b
        commit
        checkout release
        merge develop tag: "v4 (SAT)"
        checkout develop
        commit

6️⃣ Hotfix branches

Hotfix branches are used to quickly patch critical issues in the LIVE environment. They are similar to bugfix branches but always originate from the master branch, since they address production incidents.

• Hotfix branches are created from the master branch.
• Once the fix is complete and tested, it must be merged back into master via a pull request.
• The master branch should be tagged with a new LIVE version number.
• The hotfix must also be merged into develop branch to ensure future development includes the fix.
• This ensures all branches remain consistent with the LIVE system.

---
    config:
        theme: 'base'
        gitGraph:
            mainBranchName: 'master'
            showCommitLabel: false
---
    gitGraph
        commit
        branch release
        branch develop
        commit
        checkout release
        merge develop tag: "v1 (SAT)"
        checkout master
        merge release
        branch hotfix/fix-bug-a
        commit
        commit
        checkout master
        merge hotfix/fix-bug-a tag: "v1.1 (LIVE)"
        checkout develop
        merge hotfix/fix-bug-a
        checkout develop
        commit
        commit
        checkout release
        merge develop tag: "v2 (SAT)"
        checkout master
        merge release

---

Pull request flow

A pull request is a development process that provides a platform for discussion and review of a completed feature. Its purpose is to notify developers that the feature has been completed and it is open for discussion or modifications. The discussion usually occurs to improve the quality of the code; it is basically a code review process.

What Needs to Be Done Before Creating a Pull Request?

1. Commit code in your feature branch. Note that a feature can have any number of commits.
2. Commits made in the branch only reflect changes on the local machine (i.e. your machine). So, the commits need to be pushed to the remote branch.
3. Then, you’re ready to rebase your branch. Rebasing is required if any new pull requests were merged after you had taken the feature branch.
4. After rebasing, any conflicts that arise need to be resolved, and the code needs to be pushed back to the remote branch.
5. Finally, it’s time to create a pull request.

Note: Pull requests require two distinct branches. There needs to be a difference in the code between the taken branch and source branch.

Pull Request Process

1. When creating a pull request, you add a brief overview of your feature, select the branch to which the code needs to be merged, and select the assignee who will be reviewing it.
2. Once it is created, it is open for discussion or modifications.
3. Sometimes conflicts occur after creating a pull request, and you must resolve these conflicts.
4. Usually, the Team Leader reviews the code, but it is not mandatory that only the assignee performs the review. Any developer can take part in the review process and give their feedback or discuss potential modifications to the code.
5. Any feedback or modifications are added in the form of comments near the code line.
6. The developer resolves comments and replies to the reviewer.
7. This process continues until all comments are resolved.
8. Once all discussions are resolved, the code is merged to the branch that was selected when the pull request was created.

Note: Pull requests can be made for any branch. Usually, they are made for the source branch. Sometimes it is okay to close a pull request without merging it. This usually occurs when a feature is dropped.

Benefits of Pull Requests

• Use this collaborative platform to discuss potential modifications to the code.
• Improve code quality.
• Simplify the process of receiving feedback from the reviewer.
• Address feedback easily in-line near the relevant code.
• Provide better stability for the code.

flowchart TB
    A(["Source branch"]) --> B[Developer takes a feature branch]
    B --> C[Makes modifications in code]
    C --> D[Commits code]
    D --> E{Is implementation completed?}
    E -->|No| C
    E -->|Yes| F[Pushes changes to remote branch]
    F --> G[Create/Update pull request]
    G --> H{Conflicts?}
    H -->|Yes| I[Takes update from source and resolve conflicts]
    I --> C
    H -->|No| J{Discussion}
    J -->|No| C
    J -->|Yes| K(["Code Merge To Source Branch"])

What Are Merge Conflicts and When Do They Occur in a Pull Request?

To better explain what conflicts are, consider a scenario where developer A takes a branch, feature A, from the develop branch. Another developer, developer B, takes a branch, feature B, from the develop branch.

Now both developers work on their respective feature branches. Developer A modifies a line or a block of code in the feature A branch. Developer B also modifies the same block of code that developer A has modified but in the feature B branch.

After completing their features, both developers create pull requests to the develop branch; let’s call them pull request A and pull request B. Then, a reviewer merges A. Once A is merged, a conflict arises in B because the same block of code was modified by both developers.

To resolve the conflict, developer B must rebase the feature B branch by retrieving an update from the develop branch (i.e. the source branch). After retrieving the update, developer B faces code conflicts in their local copy of the branch. Now they must resolve the conflicts and again, commit, and push code to the remote develop branch. Now the code is free of conflicts, so B can be merged by the reviewer.

---

Workflow Example

1. Developer creates feature/new-feature from develop.
2. Developer pushes changes and opens a Pull Request to develop.
3. After review and approval, the feature is merged into develop.
4. Merge develop into release via Pull Request, make a SAT version is created from release and tagged with a version number.
5. QA tests and approves the SAT version.
6. Merge release into master for production and back into develop via Pull Request.
7. If a production bug is found, a hotfix/critical-payment-bug branch is created from master, fixed, and merged into both master and develop.
8. Make a new LIVE version from master and tagged with a version number.

---
    config:
        theme: 'base'
        gitGraph:
            mainBranchName: 'master'
            showCommitLabel: false
---
    gitGraph
        commit
        branch release
        branch develop
        checkout develop
        branch feature/new-feature
        commit 
        checkout develop
        merge feature/new-feature
        checkout release
        merge develop tag: "v1"
        checkout master
        merge release
        branch hotfix/critical-bug
        commit 
        checkout master
        merge hotfix/critical-bug tag: "v1_1"
        checkout develop
        merge hotfix/critical-bug

---

Commit Message Guidelines

To ensure a clean and readable history, commit messages should follow the Conventional Commits format:

<type>(<scope>): <short description>

Types:

• feat: new feature
• fix: bug fix
• chore: maintenance / tooling changes
• docs: documentation updates
• refactor: code refactor without feature changes
• test: adding or updating tests

Example commits:

• feat(auth): add login API integration
• fix(ui): resolve button alignment issue on mobile
• docs(git): update branching guidelines

---

1. Site Acceptance Test ↩︎