--- id: 02-gitflow title: 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. ```mermaid --- 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**[^1] 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. ```mermaid --- 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. ```mermaid --- 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. ```mermaid --- 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. ```mermaid --- 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. ```mermaid --- 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. ```mermaid 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. ```mermaid --- 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: ``` (): ``` **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