GitFlow Process Overview

GitFlow is a branching model for Git, proposed by Vincent Driessen, that provides a structured workflow to
manage feature development, releases, and hotfixes. It emphasizes the use of dedicated branches for
specific tasks, which makes collaboration and version control easier, especially for teams working on large
or complex projects.

Key Branches in GitFlow

1. Main Branch (master/main)
- The stable production branch.
- Always contains the code in production or ready for production.
- Only updated through completed releases or hotfixes.

2. Develop Branch
- The integration branch for ongoing development.
- Developers branch off from here to work on features and bug fixes.
- After features are complete and tested, they are merged back into the develop branch.
- Represents the latest completed development, but not yet released.

3. Feature Branches
- Used to develop new features.
- Branch from the `develop` branch and merge back into it when the feature is complete and tested.
- Named conventionally as `feature/feature-name`.

4. User story branches

- Used for working on user stories
- Branch from the “feature” branch and merged back to it when user story is complete and unit tested
- Named conventionally as “feature/feature-name/jira-story”

5. Release Branches
- Created from the `develop` branch when preparing for a new production release.
- Dedicated to release preparations (e.g., testing, bug fixing, and final tweaks).
- Merges into both `main` and `develop` after the release is finalized.
- Named as `release/release-name`.

6. Hotfix Branches
- Used for quick fixes on the production code (i.e., emergencies).
- Branch from `main` and merge back into both `main` and `develop` to ensure the fixes are reflected
in the ongoing development.

GitFlow Process Diagram

Environment Branch Comments
DEV Develop Keeps development code up-to-date
e.g., release/projectA, release/project. This may vary
if multiple projects are being worked on
QA Release
simultaneously, please refer to the FAQ section for
more details
UAT/ML Release e.g., release/projectA, release/project
Production MAIN
Training MAIN

1. Feature Development
- Developers create a `feature/` branch from `develop` to work on individual tasks.
- Once the feature is complete, it's merged back into `develop`.
2. Release Preparation
- When ready for release, a `release/` branch is created from `develop`.
- Bug fixes or final adjustments are made here.
- The release branch is merged into both `main` and `develop`.
3. Hotfixes
- If a critical bug is found in production, a `hotfix/` branch is created from `main`.
- The fix is made and merged back into both `main` and `develop` to keep the branches in sync.
Benefits of GitFlow vs. Using Main as the Release Branch
1. Structured Workflow
- GitFlow provides a structured workflow that clearly defines the purpose of each branch. This avoids
confusion and helps teams work on features, bug fixes, and releases without interfering with each
other.

2. Isolated Feature Development

- Developers work on feature branches, which are isolated from the main codebase. This prevents
incomplete features or untested code from being merged into the production branch prematurely.

3. Clear Release Process

- The use of dedicated `release` branches ensures that there is a formalized process for preparing a
release. Testing, bug fixing, and minor tweaks happen on the release branch without disrupting
ongoing development in `develop`.

4. Safe Hotfixes
- Hotfixes can be applied directly to the `main` branch without interrupting the development process.
Since the hotfix is also merged back into `develop`, the changes are carried forward into future
releases.

5. Collaborative Development
- GitFlow makes it easy for multiple developers to collaborate on different features without conflict. The
branching model encourages isolation and regular integration into the develop branch, which reduces
merge conflicts and ensures a smooth workflow.
 6. Improved Stability
- Since `main` only contains production-ready code, it remains stable. There’s no risk of accidentally
deploying incomplete or unstable features to production.

7. Better Version Control

- With dedicated release branches, versioning becomes easier to manage. Each release is formalized,
and the history of changes between versions is clearly tracked.

Conclusion
GitFlow offers a more organized and controlled way to handle feature development, releases, and urgent
fixes compared to working directly off the `main` branch. It helps teams avoid merge conflicts, improve
code stability, and ensure that releases are well-prepared. For teams looking for a more robust workflow,
GitFlow can streamline processes and improve collaboration.
FAQ
1. What if we find a bug in UAT?
Code is branched off from release branch and pushed back to QA and UAT. We do not merge back to
DEVELOP until the release is deployed to Production.

2. How is the release merged back to develop and main?

After production deployment, release branch is merged to MAIN and then to DEVELOP. MAIN branch is
NOT merged to DEVELOP. This avoids sometimes pulling Production-specific changes (like hotfixes) to
develop that might not be relevant to ongoing development work.

3. What if we have multiple projects working simultaneously?

An ideal scenario, where only 1 ongoing project:
1) Team lead creates a feature branch off develop, e.g., feature/project
2) Developers create a user story branch from the feature branch to work on, e.g., story/project-24
3) Developers merge the user story branch to feature branch once complete
4) Once the feature story branch is ready, it is merged back to develop
5) Develop branch is deployed to development environment for smoke/unit testing
6) Once verified on development environment, release branch is created for QA, e.g., release/24.10.2
7) Release branch is deployed and tested on QA. Purpose of QA testing is for bug fixes, regression testing,
functional testing, technical validation
8) Once verified, the same release branch is deployed to UAT. Purpose of UAT is to test business logic, user
experience, final acceptance by stakeholders
9) Once verified in UAT, the release branch is deployed to Production
10) After production deployment, we have 1 week of hypersupport. Once hypersupport is complete, code is merged
to MAIN and DEVELOP
11) The MAIN branch can then be deployed to TRAINING environment

An ideal scenario, where 2+ projects are ongoing:

1) Team/Group leads create feature branches off develop, e.g., feature/projectA and feature/projectB
2) Developers create a user story branch from their respective feature branch to work on, e.g.,
feature/projectA/jira-story, feature/projectB/jira-story
3) Once development is completed in the jira-story branch, this is merged to the feature branch.
4) Feature branch is then deployed to the development environment for unit testing
5) Once user story branch is dev tested, it is merged to the feature branch for their respective project, e.g.,
feature/projectA
6) The respective feature branch is then deployed to QA environment for additional testing – each feature will
require an isolated environment for testing. Testing feature branches independently in QA will provide a quicker
identification of bugs and these will be independent of any other projects that are simultaneously being worked
on
7) Once the feature branch is tested successfully on QA, it is then merged to the release branch.
8) Once verified, the same release branch is deployed to UAT
9) Once verified in UAT, the release branch is deployed to Production
10) After production deployment, there is at least 1 week of hypersupport. Once hypersupport is complete, code is
merged to MAIN and DEVELOP as well as to the release branch of other projects.
11) Once code is synced on all branches, the JIRA story can be moved to COMPLETE.
12) The MAIN branch can then be deployed to TRAINING environment

4. Does HOTFIX get merged to current release branch if HOTFIX was just released to
Production?
HOTFIX gets merged to MAIN and DEVELOP branch once released to Production. Any project queued for
release should be updated from the MAIN branch as per GITFlow.

5. What are the branch naming conventions?

For branch naming conventions, the following should be followed:
a) Release: Release branches should be label as such: release/v24.5.1. Depending on whether multiple
projects are being worked on in the code base, the release branches may have an additional project
layer when being created. e.g., release/fleet/v1.0.0
b) Feature: Feature branches follow similar conventions, but numbers are not necessarily required,
e.g., feature/fleet-api, feature/iop-api
c) User story: User story branches are child branches for feature branches and labeled as such:
feature/fleet-api/flcnfas-128. Having the user story under the feature branch will ensure that we are
able to identify to which project the branch belongs
Additionally, branch names should all be in lowercase and user hyphens for better readability.
Bibliography
Atlassian. (2024). Gitflow workflow. Retrieved from Atlassian:
https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow