Debian Codegraph @

doc/contributing/gitworkflow.rst

raw
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 - ``feature/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 Release Branch
35 ^^^^^^^^^^^^^^
36
37 - ``release``: Represents the current maintenance line for patch releases.
38
39 - Created from ``main`` after a stable release when the first patch is needed.
40 - Accepts ``fix/xxx`` and ``hotfix/xxx`` branch merges.
41 - Merged back into ``main`` for each patch release tag (e.g., 1.0.1, 1.0.2).
42 - Reset or recreated when starting a new minor/major release cycle.
43
44 .. note::
45
46 The ``release`` branch is not versioned (no ``release/1.0.x``). It always
47 represents "the current maintenance line." When a new minor version is released
48 (e.g., 1.2.0), the old ``release`` branch is deleted and a new one is created
49 from the fresh tag when the first patch for 1.2.1 is needed.
50
51 Bug Fix Branches
52 ^^^^^^^^^^^^^^^^
53
54 - ``fix/xxx``: Used for general bug fixes that are not urgent.
55
56 - Created from ``develop`` (for next feature release) or ``release`` (for patch release).
57 - Merged back into the originating branch once completed.
58 - Deleted after merging.
59
60 - ``hotfix/xxx``: Used for urgent production-critical fixes.
61
62 - Created from ``release`` (if exists) or ``main`` (if no ``release`` branch yet).
63 - Merged back into ``release`` or ``main``.
64 - The fix is then cherry-picked into ``develop``.
65 - Deleted after merging.
66
67 .. note::
68
69 Hotfixes (high-priority fixes) will be integrated in the next maintenance
70 release (X.Y.Z -> Z+1), while fixes (low-priority fixes) will be integrated
71 in the next feature release (X.Y -> Y+1).
72
73
74 Documentation Branches
75 ----------------------
76
77 When working on documentation that is not related to source code
78 (e.g. training materials, user guides), branches should be named
79 using the ``doc/`` prefix.
80
81 Examples:
82
83 - ``doc/training-materials``
84 - ``doc/user-guide``
85
86 This naming convention improves clarity by clearly separating
87 documentation efforts from code-related development (features, fixes, etc.).
88
89
90 Workflow for New Features
91 -------------------------
92
93 1. Create a new feature branch from ``develop``:
94
95 .. code-block:: sh
96
97 git checkout develop
98 git checkout -b develop/feature_name
99
100 2. Develop the feature and commit changes.
101
102 3. Merge the feature branch back into ``develop``:
103
104 .. code-block:: sh
105
106 git checkout develop
107 git merge --no-ff develop/feature_name
108
109 4. Delete the feature branch:
110
111 .. code-block:: sh
112
113 git branch -d develop/feature_name
114
115 .. warning::
116
117 Do not leave feature branches unmerged for too long.
118 Regularly rebase them on ``develop`` to minimize conflicts.
119
120 Workflow for Regular Bug Fixes
121 ------------------------------
122
123 For next feature release (target: ``develop``):
124
125 1. Create a bug fix branch from ``develop``:
126
127 .. code-block:: sh
128
129 git checkout develop
130 git checkout -b fix/bug_description
131
132 2. Apply the fix and commit changes.
133
134 3. Merge the fix branch back into ``develop``:
135
136 .. code-block:: sh
137
138 git checkout develop
139 git merge --no-ff fix/bug_description
140
141 4. Delete the fix branch:
142
143 .. code-block:: sh
144
145 git branch -d fix/bug_description
146
147 For current maintenance release (target: ``release``):
148
149 1. Create a bug fix branch from ``release``:
150
151 .. code-block:: sh
152
153 git checkout release
154 git checkout -b fix/bug_description
155
156 2. Apply the fix and commit changes.
157
158 3. Merge the fix branch back into ``release``:
159
160 .. code-block:: sh
161
162 git checkout release
163 git merge --no-ff fix/bug_description
164
165 4. Delete the fix branch:
166
167 .. code-block:: sh
168
169 git branch -d fix/bug_description
170
171 .. warning::
172
173 Do not create a ``fix/xxx`` branch from a ``develop/feature_name`` branch.
174 Always branch from ``develop`` or ``release`` to ensure fixes are correctly propagated.
175
176 .. code-block:: sh
177
178 # Incorrect:
179 git checkout develop/feature_name
180 git checkout -b fix/wrong_branch
181
182 .. code-block:: sh
183
184 # Correct:
185 git checkout develop
186 git checkout -b fix/correct_branch
187
188 Workflow for Critical Hotfixes
189 ------------------------------
190
191 1. Create a hotfix branch from ``release`` (or ``main`` if no ``release`` branch exists):
192
193 .. code-block:: sh
194
195 git checkout release # or: git checkout main
196 git checkout -b hotfix/critical_bug
197
198 2. Apply the fix and commit changes.
199
200 3. Merge the fix back into ``release`` (or ``main``):
201
202 .. code-block:: sh
203
204 git checkout release # or: git checkout main
205 git merge --no-ff hotfix/critical_bug
206
207 4. Cherry-pick the fix into ``develop``:
208
209 .. code-block:: sh
210
211 git checkout develop
212 git cherry-pick <commit_hash>
213
214 5. Delete the hotfix branch:
215
216 .. code-block:: sh
217
218 git branch -d hotfix/critical_bug
219
220 .. warning::
221
222 Do not merge ``fix/xxx`` or ``hotfix/xxx`` directly into ``main`` without following the workflow.
223 Ensure hotfixes are cherry-picked into ``develop`` to avoid losing fixes in future releases.
224
225 Workflow for Patch Releases
226 ----------------------------
227
228 When ready to release a patch version (e.g., 1.0.1, 1.0.2):
229
230 1. Ensure the ``release`` branch contains all desired fixes.
231
232 2. Merge ``release`` into ``main``:
233
234 .. code-block:: sh
235
236 git checkout main
237 git merge --no-ff release
238
239 3. Tag the release on ``main``:
240
241 .. code-block:: sh
242
243 git tag -a v1.0.1 -m "Release version 1.0.1"
244 git push origin main --tags
245
246 4. Keep the ``release`` branch for additional patches in the same minor version series.
247
248 Workflow for Minor/Major Releases
249 ----------------------------------
250
251 When ready to release a new minor or major version (e.g., 1.1.0, 2.0.0):
252
253 1. Merge ``develop`` into ``main``:
254
255 .. code-block:: sh
256
257 git checkout main
258 git merge --no-ff develop
259
260 2. Tag the release on ``main``:
261
262 .. code-block:: sh
263
264 git tag -a v1.1.0 -m "Release version 1.1.0"
265 git push origin main --tags
266
267 3. Delete the old ``release`` branch (if exists):
268
269 .. code-block:: sh
270
271 git branch -d release
272 git push origin --delete release
273
274 4. Create a new ``release`` branch from ``main`` when the first patch for 1.1.1 is needed:
275
276 .. code-block:: sh
277
278 git checkout main
279 git checkout -b release
280 git push -u origin release
281
282 Best Practices
283 --------------
284
285 - Regularly **rebase feature branches** on ``develop`` to stay up to date:
286
287 .. code-block:: sh
288
289 git checkout develop/feature_name
290 git rebase develop
291
292 - Avoid long-lived branches to minimize merge conflicts.
293
294 - Ensure bug fixes in ``release`` or ``main`` are **always cherry-picked** to ``develop``.
295
296 - Clearly differentiate between ``fix/xxx`` (non-urgent fixes) and ``hotfix/xxx`` (critical production fixes).
297
298 - When creating the ``release`` branch, update release notes to indicate which version it targets (e.g., add a comment in the merge commit: "Create release branch for v1.0.x maintenance").
299
300 - The ``release`` branch always represents the current maintenance line. To know which version it targets, check the most recent tag on ``main`` or the release notes.
301
302 Takeaway
303 --------
304
305 This workflow ensures a structured yet flexible development process while keeping
306 ``main`` stable and ``develop`` always updated with the latest changes.
307
308 The ``release`` branch provides a dedicated maintenance line for patch releases,
309 allowing ``develop`` to proceed with new features without interference. This solves
310 the problem of coordinating unreleased changes across the PlotPyStack ecosystem
311 (DataLab, Sigima, PlotPy, guidata, PythonQwt) by providing a stable branch for
312 CI testing during maintenance cycles.