dev-public/doc-development-workflow
19
0
Fork 0
Code Issues Pull Requests Actions Projects Releases Activity
doc-development-workflow/docs/02-version-control/01-gitflow.md
Le Hoang Nam b432ce83f3 Replace Git Workflow category with Version Control category and add Gitflow and Git Management documents 
- Deleted the obsolete Git Workflow category.
- Introduced a new Version Control category with a comprehensive guide to Git workflow, branching strategies, and repository management.
- Added Gitflow document detailing branching strategies and release management.
- Added Git Management document outlining Git policies, permissions, and branch protection rules.
2025-09-12 16:42:09 +07:00

401 lines
14 KiB
Markdown
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
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:
```
<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
Reference in New Issue View Git Blame Copy Permalink