Le Hoang Nam
7dc995dcd9
- Created a new Docusaurus project for documentation. - Added configuration file `docusaurus.config.ts` for site settings and theme. - Established initial documentation structure with overview and GitFlow sections. - Included a `.gitignore` file to exclude unnecessary files and directories. - Added essential files such as `package.json`, `package-lock.json`, and initial CSS styles. - Removed outdated guides related to Gitea and Jenkins management.
324 lines
12 KiB
Markdown
324 lines
12 KiB
Markdown
---
|
||
id: 02-gitflow
|
||
title: Gitflow
|
||
---
|
||
|
||
## **Overview**
|
||
|
||
Gitflow is really just an abstract idea of a Git workflow. This means it dictates what kind of branches to set up and how to merge them together. We will touch on the purposes of the branches below.
|
||
|
||
## **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 team members 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 assigned person reviews the code, but it is not mandatory that only the assignee performs the review. Any team member 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.
|
||
|
||
---
|
||
|
||
[^1]: Site Acceptance Test |