Skip to content

Commit 450acc8

Browse files
PierreRaybautPierreRaybaut
committed
Add: update Git workflow documentation and include release branch in CI configuration
1 parent 8fe3174 commit 450acc8

File tree

3 files changed

+332
-3
lines changed

3 files changed

+332
-3
lines changed

‎.github/workflows/test_pyqt5.yml‎

Lines changed: 20 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,9 @@ name: Build, install and test with PyQt5
77

88
on:
99
push:
10-
branches: [ "master", "develop" ]
10+
branches: [ "master", "develop", "release" ]
1111
pull_request:
12-
branches: [ "master", "develop" ]
12+
branches: [ "master", "develop", "release" ]
1313

1414
jobs:
1515
build:
@@ -52,8 +52,25 @@ jobs:
5252
pip install -r deps.txt
5353
# Install PlotPy without dependencies
5454
pip install --no-deps .
55+
elif [ "${{ github.ref_name }}" = "release" ]; then
56+
pip uninstall -y guidata PythonQwt
57+
cd ..
58+
# Try cloning guidata from release, fallback to main or master
59+
git clone --depth 1 --branch release https://github.com/PlotPyStack/guidata.git || git clone --depth 1 https://github.com/PlotPyStack/guidata.git || git clone --depth 1 --branch master https://github.com/PlotPyStack/guidata.git
60+
# Try cloning PythonQwt from main or master
61+
git clone --depth 1 https://github.com/PlotPyStack/PythonQwt.git || git clone --depth 1 --branch master https://github.com/PlotPyStack/PythonQwt.git
62+
cd PlotPy
63+
pip install -e ../guidata
64+
pip install -e ../PythonQwt
65+
# Install tomli for TOML parsing (safe if already present)
66+
pip install tomli
67+
# Extract dependencies and save to file, then install
68+
python -c "import tomli; f=open('pyproject.toml','rb'); data=tomli.load(f); deps=[d for d in data['project']['dependencies'] if not any(p in d for p in ['guidata', 'PythonQwt'])]; open('deps.txt','w').write('\n'.join(deps))"
69+
pip install -r deps.txt
70+
# Install PlotPy without dependencies
71+
pip install --no-deps .
5572
else
56-
# Install from PyPI normally for main branch
73+
# Install from PyPI normally for master branch
5774
pip install .[test]
5875
fi
5976
- name: Lint with Ruff

‎doc/dev/gitworkflow.rst‎

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

‎doc/dev/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ Development
66
:caption: Contents:
77

88
contribute
9+
gitworkflow
910
build
1011
guiqwt_to_plotpy
1112
v1_to_v2

0 commit comments

Comments
 (0)