Skip to content

Commit 43989a6

Browse files
PierreRaybautPierreRaybaut
committed
Doc: new page on DataLab's project Git workflow
1 parent e77e637 commit 43989a6

File tree

3 files changed

+415
-0
lines changed

3 files changed

+415
-0
lines changed

‎doc/contributing/gitworkflow.rst‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
.. _gitworkflow:
2+
3+
Git Workflow
4+
============
5+
6+
This document describes the Git workflow used in the DataLab project,
7+
based on a ``main`` branch, a ``develop`` branch, and feature-specific branches.
8+
It also defines how bug fixes are managed.
9+
10+
.. note::
11+
12+
This workflow is a simplified version of the `Gitflow Workflow <https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow>`_.
13+
It has been adapted to suit the needs of the DataLab project at the current stage of development.
14+
In the near future, we may consider adopting a more complex workflow, e.g. by adding release branches.
15+
16+
Branching Model
17+
---------------
18+
19+
Main Branches
20+
^^^^^^^^^^^^^
21+
22+
- ``main``: Represents the stable, production-ready version of the project.
23+
- ``develop``: Used for ongoing development and integration of new features.
24+
25+
Feature Branches
26+
^^^^^^^^^^^^^^^^
27+
28+
- ``develop/feature_name``: Used for the development of new features.
29+
30+
- Created from ``develop``.
31+
- Merged back into ``develop`` once completed.
32+
- Deleted after merging.
33+
34+
Bug Fix Branches
35+
^^^^^^^^^^^^^^^^
36+
37+
- ``fix/xxx``: Used for general bug fixes that are not urgent.
38+
39+
- Created from ``develop``.
40+
- Merged back into ``develop`` once completed.
41+
- Deleted after merging.
42+
43+
- ``hotfix/xxx``: Used for urgent production-critical fixes.
44+
45+
- Created from ``main``.
46+
- Merged back into ``main``.
47+
- The fix is then cherry-picked into ``develop``.
48+
- Deleted after merging.
49+
50+
.. note::
51+
52+
Hotfixes (high-priority fixes) will be integrated in the next maintenance
53+
release (X.Y.Z -> Z+1), while fixes (low-priority fixes) will be integrated
54+
in the next feature release (X.Y -> Y+1).
55+
56+
Workflow for New Features
57+
-------------------------
58+
59+
1. Create a new feature branch from ``develop``:
60+
61+
.. code-block:: sh
62+
63+
git checkout develop
64+
git checkout -b develop/feature_name
65+
66+
2. Develop the feature and commit changes.
67+
68+
3. Merge the feature branch back into ``develop``:
69+
70+
.. code-block:: sh
71+
72+
git checkout develop
73+
git merge --no-ff develop/feature_name
74+
75+
4. Delete the feature branch:
76+
77+
.. code-block:: sh
78+
79+
git branch -d develop/feature_name
80+
81+
.. warning::
82+
83+
Do not leave feature branches unmerged for too long.
84+
Regularly rebase them on ``develop`` to minimize conflicts.
85+
86+
Workflow for Regular Bug Fixes
87+
------------------------------
88+
89+
1. Create a bug fix branch from ``develop``:
90+
91+
.. code-block:: sh
92+
93+
git checkout develop
94+
git checkout -b fix/bug_description
95+
96+
2. Apply the fix and commit changes.
97+
98+
3. Merge the fix branch back into ``develop``:
99+
100+
.. code-block:: sh
101+
102+
git checkout develop
103+
git merge --no-ff fix/bug_description
104+
105+
4. Delete the fix branch:
106+
107+
.. code-block:: sh
108+
109+
git branch -d fix/bug_description
110+
111+
.. warning::
112+
113+
Do not create a ``fix/xxx`` branch from a ``develop/feature_name`` branch.
114+
Always branch from ``develop`` to ensure fixes are correctly propagated.
115+
116+
.. code-block:: sh
117+
118+
# Incorrect:
119+
git checkout develop/feature_name
120+
git checkout -b fix/wrong_branch
121+
122+
.. code-block:: sh
123+
124+
# Correct:
125+
git checkout develop
126+
git checkout -b fix/correct_branch
127+
128+
Workflow for Critical Hotfixes
129+
------------------------------
130+
131+
1. Create a hotfix branch from ``main``:
132+
133+
.. code-block:: sh
134+
135+
git checkout main
136+
git checkout -b hotfix/critical_bug
137+
138+
2. Apply the fix and commit changes.
139+
140+
3. Merge the fix back into ``main``:
141+
142+
.. code-block:: sh
143+
144+
git checkout main
145+
git merge --no-ff hotfix/critical_bug
146+
147+
4. Cherry-pick the fix into ``develop``:
148+
149+
.. code-block:: sh
150+
151+
git checkout develop
152+
git cherry-pick <commit_hash>
153+
154+
5. Delete the hotfix branch:
155+
156+
.. code-block:: sh
157+
158+
git branch -d hotfix/critical_bug
159+
160+
.. warning::
161+
162+
Do not merge ``fix/xxx`` or ``hotfix/xxx`` directly into ``main`` without following the workflow.
163+
Ensure hotfixes are cherry-picked into ``develop`` to avoid losing fixes in future releases.
164+
165+
Best Practices
166+
--------------
167+
168+
- Regularly **rebase feature branches** on ``develop`` to stay up to date:
169+
170+
.. code-block:: sh
171+
172+
git checkout develop/feature_name
173+
git rebase develop
174+
175+
- Avoid long-lived branches to minimize merge conflicts.
176+
177+
- Ensure bug fixes in ``main`` are **always cherry-picked** to ``develop``.
178+
179+
- Clearly differentiate between ``fix/xxx`` (non-urgent fixes) and ``hotfix/xxx`` (critical production fixes).
180+
181+
Takeaway
182+
--------
183+
184+
This workflow ensures a structured yet flexible development process while keeping
185+
``main`` stable and ``develop`` always updated with the latest changes.
186+
187+
It also ensures that bug fixes are correctly managed and propagated across branches.

‎doc/contributing/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -118,6 +118,7 @@ bugs or implementing new features.
118118

119119
contribute_code
120120
guidelines
121+
gitworkflow
121122
environment
122123
roadmap
123124
changelog

0 commit comments

Comments
 (0)