From b749fbad29374d8b11e9b2d80adc71c8405d02ed Mon Sep 17 00:00:00 2001
From: Michael Boniface <m.j.boniface@soton.ac.uk>
Date: Sat, 22 Feb 2025 14:59:42 +0000
Subject: [PATCH] docs (documentation): git workflow documentation

---
 docs/index.md | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 61 insertions(+), 1 deletion(-)

diff --git a/docs/index.md b/docs/index.md
index 4ef8d11..84eb5b0 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -171,4 +171,64 @@ The `phen` command is used phenotype-related operations.
   ```
 
   - `-d`, `--phen-dir`: (Optional) Directory of current phenotype configuration (the default is ./build/phen).
-  - `-old`, `--phen-dir-old`: (Required) Directory of old phenotype version)
\ No newline at end of file
+  - `-old`, `--phen-dir-old`: (Required) Directory of old phenotype version)
+ 
+# GitLab Workflow for Managing Releases
+
+## Branching Strategy
+
+### 1. Main Branch (`main`)
+- Represents the stable production-ready code.
+- Contains only release versions.
+- Direct commits are not allowed; changes must go through a pull request (PR) from `dev`.
+- Merges into `main` require authorization from a repository maintainer or admin.
+- Protected branch settings should enforce code reviews and approvals before merging.
+
+### 2. Development Branch (`dev`)
+- Used for integration and testing.
+- All feature branches must be merged here first before reaching `main`.
+- Regularly synced with `main` to keep it up to date.
+
+### 3. Feature Branches (`feature-xxx`)
+- Created for each issue or feature.
+- Always branch from `dev` based on an issue.
+- Named according to the issue number and short description (e.g., `feature-123-user-auth`).
+- Can be created directly from the issue page in GitLab by selecting "Create Branch".
+- Merged into `dev` through a pull request.
+
+## Pull Request Sequence
+
+1. **Create a Feature Branch**
+   - Branch from `dev`: `git checkout -b feature-xxx dev`
+   - Alternatively, create the branch from the issue itself in GitLab.
+   - Implement feature and commit changes following commit message guidelines.
+
+2. **Push the Branch**
+   - `git push origin feature-xxx`
+
+3. **Create a Merge Request (MR) to `dev`**
+   - Ensure code review and approvals before merging.
+   - Resolve conflicts if any.
+   
+4. **Merge to `dev`**
+   - Squash and merge when approved.
+   - Delete feature branch after successful merge.
+
+5. **Release to `main`**
+   - Create a merge request from `dev` to `main`.
+   - Perform final testing.
+   - Tag the release with versioning (e.g., `v1.0.0`).
+   - Deploy to production after approval.
+   - Requires authorization from a repository maintainer or admin before merging.
+
+## Commit Message Guidelines
+- Use clear and descriptive commit messages.
+- Format: `<type>(<scope>): <description>`
+- Example: `docs (documentation): git workflow documentation`
+- Types: `feat` (feature), `fix` (bug fix), `docs` (documentation), `refactor` (code refactoring), `test` (tests), `chore` (maintenance).
+
+## Additional Guidelines
+- Always pull the latest changes before starting a new feature: `git pull origin dev`
+- Write unit tests for new features.
+- Keep feature branches short-lived and regularly updated with `dev`.
+
-- 
GitLab