Git Workflow#

This document describes the Git workflow used in the DataLab project, based on a main branch, a develop branch, and feature-specific branches. It also defines how bug fixes are managed.

Note

This workflow is a simplified version of the Gitflow Workflow. It has been adapted to suit the needs of the DataLab project at the current stage of development. In the near future, we may consider adopting a more complex workflow, e.g. by adding release branches.

Branching Model#

Main Branches#

main: Represents the stable, production-ready version of the project.
develop: Used for ongoing development and integration of new features.

Feature Branches#

develop/feature_name: Used for the development of new features.
- Created from develop.
- Merged back into develop once completed.
- Deleted after merging.

Bug Fix Branches#

fix/xxx: Used for general bug fixes that are not urgent.
- Created from develop.
- Merged back into develop once completed.
- Deleted after merging.
hotfix/xxx: Used for urgent production-critical fixes.
- Created from main.
- Merged back into main.
- The fix is then cherry-picked into develop.
- Deleted after merging.

Note

Hotfixes (high-priority fixes) will be integrated in the next maintenance release (X.Y.Z -> Z+1), while fixes (low-priority fixes) will be integrated in the next feature release (X.Y -> Y+1).

Workflow for New Features#

Create a new feature branch from develop:

git checkout develop
git checkout -b develop/feature_name

Develop the feature and commit changes.

Merge the feature branch back into develop:

git checkout develop
git merge --no-ff develop/feature_name

Delete the feature branch:
```
git branch -d develop/feature_name
```

Warning

Do not leave feature branches unmerged for too long. Regularly rebase them on develop to minimize conflicts.

Workflow for Regular Bug Fixes#

Create a bug fix branch from develop:

git checkout develop
git checkout -b fix/bug_description

Apply the fix and commit changes.

Merge the fix branch back into develop:

git checkout develop
git merge --no-ff fix/bug_description

Delete the fix branch:
```
git branch -d fix/bug_description
```

Warning

Do not create a fix/xxx branch from a develop/feature_name branch. Always branch from develop to ensure fixes are correctly propagated.

# Incorrect:
git checkout develop/feature_name
git checkout -b fix/wrong_branch

# Correct:
git checkout develop
git checkout -b fix/correct_branch

Workflow for Critical Hotfixes#

Create a hotfix branch from main:

git checkout main
git checkout -b hotfix/critical_bug

Apply the fix and commit changes.

Merge the fix back into main:

git checkout main
git merge --no-ff hotfix/critical_bug

Cherry-pick the fix into develop:

git checkout develop
git cherry-pick <commit_hash>

Delete the hotfix branch:
```
git branch -d hotfix/critical_bug
```

Warning

Do not merge fix/xxx or hotfix/xxx directly into main without following the workflow. Ensure hotfixes are cherry-picked into develop to avoid losing fixes in future releases.

Best Practices#

Regularly rebase feature branches on develop to stay up to date:
```
git checkout develop/feature_name
git rebase develop
```
Avoid long-lived branches to minimize merge conflicts.
Ensure bug fixes in main are always cherry-picked to develop.
Clearly differentiate between fix/xxx (non-urgent fixes) and hotfix/xxx (critical production fixes).

Takeaway#

This workflow ensures a structured yet flexible development process while keeping main stable and develop always updated with the latest changes.

It also ensures that bug fixes are correctly managed and propagated across branches.