Skip to content

Commit 2dad6e5

Browse files
michalharakalmichalharakal
committed
Update document describing branching model to start development branch. Also delete duplicated file.
1 parent 710dcf2 commit 2dad6e5

2 files changed

Lines changed: 314 additions & 21 deletions

File tree

‎GITFLOW.adoc‎

Lines changed: 314 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,314 @@
1+
= GitFlow Workflow
2+
:toc:
3+
:toclevels: 3
4+
:sectanchors:
5+
:sectlinks:
6+
:source-highlighter: highlight.js
7+
8+
This document describes the GitFlow workflow used in the skainet project for managing feature development, releases, and hotfixes.
9+
10+
== Overview
11+
12+
GitFlow is a branching model for Git that defines specific branch types and their purposes. It provides a robust framework for managing larger projects with scheduled releases and helps teams collaborate effectively while maintaining code stability.
13+
14+
== Branch Types
15+
16+
=== Main Branches
17+
18+
==== `main` Branch
19+
* **Purpose**: Contains production-ready code
20+
* **Lifetime**: Permanent
21+
* **Protection**: Direct commits are not allowed
22+
* **Merges from**: `release/*` and `hotfix/*` branches only
23+
24+
==== `develop` Branch
25+
* **Purpose**: Integration branch for features under development
26+
* **Lifetime**: Permanent
27+
* **Protection**: Direct commits should be minimal
28+
* **Merges from**: `feature/*`, `release/*`, and `hotfix/*` branches
29+
30+
=== Supporting Branches
31+
32+
==== Feature Branches (`feature/*`)
33+
* **Purpose**: Develop new features for upcoming releases
34+
* **Naming convention**: `feature/feature-name` or `feature/ISSUE-123-feature-name` (e.g., `feature/cnn-layers`, `feature/transformer-embeddings`)
35+
* **Branch from**: `develop`
36+
* **Merge back to**: `develop`
37+
* **Lifetime**: Until feature is complete
38+
* **Deletion**: After successful merge to `develop`
39+
40+
==== Release Branches (`release/*`)
41+
* **Purpose**: Prepare new production releases
42+
* **Naming convention**: `release/1.2.0` (following semantic versioning)
43+
* **Branch from**: `develop`
44+
* **Merge back to**: `main` and `develop`
45+
* **Lifetime**: Until release is deployed
46+
* **Activities**: Bug fixes, documentation updates, release preparation
47+
48+
==== Hotfix Branches (`hotfix/*`)
49+
* **Purpose**: Quick fixes for critical production issues
50+
* **Naming convention**: `hotfix/1.2.1` or `hotfix/critical-fix`
51+
* **Branch from**: `main`
52+
* **Merge back to**: `main` and `develop`
53+
* **Lifetime**: Until fix is deployed
54+
* **Priority**: High - should be processed immediately
55+
56+
== Workflow Diagram
57+
58+
[mermaid]
59+
....
60+
gitGraph
61+
commit id: "Initial"
62+
branch develop
63+
checkout develop
64+
commit id: "Dev setup"
65+
66+
branch feature/cnn-layers
67+
checkout feature/cnn-layers
68+
commit id: "Add conv2d layer"
69+
commit id: "Add pooling layer"
70+
71+
checkout develop
72+
merge feature/cnn-layers
73+
commit id: "Merge CNN layers"
74+
75+
branch feature/tokenizer
76+
checkout feature/tokenizer
77+
commit id: "Add word embeddings"
78+
commit id: "Add BPE tokenizer"
79+
80+
checkout develop
81+
merge feature/tokenizer
82+
commit id: "Integration"
83+
84+
branch release/1.0.0
85+
checkout release/1.0.0
86+
commit id: "Prepare v1.0.0"
87+
commit id: "Fix tests"
88+
89+
checkout main
90+
merge release/1.0.0
91+
commit id: "Release v1.0.0" tag: "v1.0.0"
92+
93+
checkout develop
94+
merge release/1.0.0
95+
96+
checkout main
97+
branch hotfix/1.0.1
98+
checkout hotfix/1.0.1
99+
commit id: "Fix gradient explosion"
100+
101+
checkout main
102+
merge hotfix/1.0.1
103+
commit id: "Hotfix v1.0.1" tag: "v1.0.1"
104+
105+
checkout develop
106+
merge hotfix/1.0.1
107+
108+
checkout develop
109+
branch feature/transformer-attention
110+
checkout feature/transformer-attention
111+
commit id: "Add self-attention"
112+
....
113+
114+
== Detailed Workflows
115+
116+
=== Feature Development
117+
118+
. Create a feature branch from `develop`:
119+
+
120+
[source,bash]
121+
----
122+
git checkout develop
123+
git pull origin develop
124+
git checkout -b feature/lstm-layers
125+
----
126+
127+
. Develop the feature with regular commits:
128+
+
129+
[source,bash]
130+
----
131+
git add .
132+
git commit -m "Implement LSTM forward pass"
133+
git push origin feature/lstm-layers
134+
----
135+
136+
. When feature is complete, create a pull request to `develop`
137+
138+
. After code review and approval, merge to `develop`:
139+
+
140+
[source,bash]
141+
----
142+
git checkout develop
143+
git pull origin develop
144+
git merge --no-ff feature/lstm-layers
145+
git push origin develop
146+
git branch -d feature/lstm-layers
147+
----
148+
149+
=== Release Process
150+
151+
. Create a release branch from `develop`:
152+
+
153+
[source,bash]
154+
----
155+
git checkout develop
156+
git pull origin develop
157+
git checkout -b release/1.2.0
158+
----
159+
160+
. Perform release preparations:
161+
** Update version numbers
162+
** Update documentation
163+
** Run final tests
164+
** Fix any release-blocking bugs
165+
166+
. When ready, merge to `main`:
167+
+
168+
[source,bash]
169+
----
170+
git checkout main
171+
git pull origin main
172+
git merge --no-ff release/1.2.0
173+
git tag -a v1.2.0 -m "Release version 1.2.0"
174+
git push origin main --tags
175+
----
176+
177+
. Merge back to `develop`:
178+
+
179+
[source,bash]
180+
----
181+
git checkout develop
182+
git merge --no-ff release/1.2.0
183+
git push origin develop
184+
git branch -d release/1.2.0
185+
----
186+
187+
=== Hotfix Process
188+
189+
. Create a hotfix branch from `main`:
190+
+
191+
[source,bash]
192+
----
193+
git checkout main
194+
git pull origin main
195+
git checkout -b hotfix/1.2.1
196+
----
197+
198+
. Implement the fix:
199+
+
200+
[source,bash]
201+
----
202+
git add .
203+
git commit -m "Fix memory leak in tensor operations"
204+
----
205+
206+
. Merge to `main`:
207+
+
208+
[source,bash]
209+
----
210+
git checkout main
211+
git merge --no-ff hotfix/1.2.1
212+
git tag -a v1.2.1 -m "Hotfix version 1.2.1"
213+
git push origin main --tags
214+
----
215+
216+
. Merge to `develop`:
217+
+
218+
[source,bash]
219+
----
220+
git checkout develop
221+
git merge --no-ff hotfix/1.2.1
222+
git push origin develop
223+
git branch -d hotfix/1.2.1
224+
----
225+
226+
== Best Practices
227+
228+
=== Branch Naming
229+
* Use descriptive names that reflect the purpose
230+
* Include issue numbers when applicable: `feature/ISSUE-123-transformer-embeddings`
231+
* Use lowercase with hyphens: `feature/add-attention-mechanism`
232+
233+
=== Commit Messages
234+
* Use present tense: "Add feature" not "Added feature"
235+
* Keep first line under 50 characters
236+
* Provide detailed description for complex changes
237+
* Reference issue numbers: "Fix gradient clipping in LSTM (closes #123)"
238+
239+
=== Pull Requests
240+
* Always create pull requests for merging to `main` and `develop`
241+
* Require code review before merging
242+
* Include comprehensive description of changes
243+
* Ensure all tests pass before merging
244+
* Use `--no-ff` flag to preserve branch history
245+
246+
=== Version Management
247+
* Follow https://semver.org/[Semantic Versioning]
248+
* Tag all releases with version numbers
249+
* Update version in project files before release
250+
* Maintain CHANGELOG.md with release notes
251+
252+
== Integration with CI/CD
253+
254+
=== Automated Testing
255+
* Run tests on all feature branches
256+
* Run comprehensive test suite on `develop` and `main`
257+
* Block merges if tests fail
258+
259+
=== Deployment Pipeline
260+
* `main` branch deploys to production
261+
* `develop` branch deploys to staging environment
262+
* Feature branches deploy to development environment for testing
263+
264+
=== Branch Protection Rules
265+
* Protect `main` and `develop` branches
266+
* Require pull request reviews
267+
* Require status checks to pass
268+
* Require branches to be up to date before merging
269+
270+
== Troubleshooting
271+
272+
=== Common Issues
273+
274+
==== Merge Conflicts
275+
When encountering merge conflicts:
276+
277+
. Update your branch with latest changes:
278+
+
279+
[source,bash]
280+
----
281+
git checkout your-branch
282+
git fetch origin
283+
git merge origin/develop
284+
----
285+
286+
. Resolve conflicts manually in your editor
287+
. Test the resolution
288+
. Commit the merge resolution
289+
290+
==== Mistaken Commits
291+
If you commit to wrong branch:
292+
293+
. Create a new branch from the correct base:
294+
+
295+
[source,bash]
296+
----
297+
git checkout correct-base-branch
298+
git checkout -b new-feature-branch
299+
git cherry-pick commit-hash
300+
----
301+
302+
. Reset the wrong branch:
303+
+
304+
[source,bash]
305+
----
306+
git checkout wrong-branch
307+
git reset --hard HEAD~1
308+
----
309+
310+
== Conclusion
311+
312+
GitFlow provides a structured approach to managing code changes in collaborative environments. By following this workflow consistently, the skainet project maintains code quality, enables parallel development, and ensures stable releases.
313+
314+
For questions or clarifications about this workflow, please refer to the original https://nvie.com/posts/a-successful-git-branching-model/[GitFlow article] or reach out to the project maintainers.

‎LICENSE‎

Lines changed: 0 additions & 21 deletions
This file was deleted.

0 commit comments

Comments
 (0)