From fbe3cd71e22761243e853af52929c96bb429f1cf Mon Sep 17 00:00:00 2001
From: Maurice Zimmnau <maurice.zimmnau@rwth-aachen.de>
Date: Wed, 25 Sep 2024 15:19:37 +0200
Subject: [PATCH] Add a merge request documentation

---
 docs/assets/images/merge-request.jpg   |  3 ++
 docs/developer/contribute.md           | 20 +++++---
 docs/developer/merge-request.md        | 70 ++++++++++++++++++++++++++
 docs/developer/review-merge-request.md | 28 +++++++++++
 docs/developer/testing.md              |  3 +-
 mkdocs.yml                             |  5 +-
 6 files changed, 119 insertions(+), 10 deletions(-)
 create mode 100644 docs/assets/images/merge-request.jpg
 create mode 100644 docs/developer/merge-request.md
 create mode 100644 docs/developer/review-merge-request.md

diff --git a/docs/assets/images/merge-request.jpg b/docs/assets/images/merge-request.jpg
new file mode 100644
index 0000000..185c647
--- /dev/null
+++ b/docs/assets/images/merge-request.jpg
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1dd84696fef1daad6bb4699fb0f4f6d972cc8de985b5c6b5eaa5972a3dd24d30
+size 74293
diff --git a/docs/developer/contribute.md b/docs/developer/contribute.md
index f65d268..f693d9d 100644
--- a/docs/developer/contribute.md
+++ b/docs/developer/contribute.md
@@ -14,16 +14,20 @@ Awesome! :sunglasses: Please make sure to read our *style guides* first:
 - Our [&rdca; C++ Code Style](style/cpp.md).
 - Our [&rdca; Python Code Style](style/python.md).
 
-## Commit rules and messages
+## How to actually contribute
 
-- Commit messages should be clear and concise.
-- Use **English** language.
-- Use the `#` to close and refer to issues. 
-- Please use **present tense** to express what the commit does.
-- **Don't** commit code which you know is not working.
+This is how you can actually make a difference:
 
-## Types of contribution
-We use *issues* and *merge request* to manage the contribution to UNICADO.
+<figure markdown>
+  ![merge-request](assets/images/merge-request.jpg){width="500"}
+  <figcaption>Merge request workflow</figcaption>
+</figure>
+
+You cloned/forked the UNICADO Package successfully acc. to the `ReadMe`. Nice! You want to make a change, e.g. fixing a bug or creating a new feature, so you create a *issue* (see also [types of contribution](#contributions)). Then you :point_up: create a feature branch, change the code and create a merge request (here a [how to](merge-request.md)). An automatic CI/CD pipeline is triggered, which helps your selected reviewer to make sure that request is ok. If it is accepted and ready-to-land :airplane:, the documentation is automatically updated. Nicely done :+1:
+
+## Types of contribution {#contributions}
+
+We use *issues* and [merge request](merge-request.md) to manage the contribution to UNICADO.
 You should always create an issue **first**, before creating the merge request.
 The issue is used to discuss and plan the required work.
 An issue should always have at least the following *labels*:
diff --git a/docs/developer/merge-request.md b/docs/developer/merge-request.md
new file mode 100644
index 0000000..9d0a860
--- /dev/null
+++ b/docs/developer/merge-request.md
@@ -0,0 +1,70 @@
+---
+title: How to create a merge request
+summary: Explains a common method to create a merge request.
+authors:
+    - Maurice Zimmnau
+date: 2024-09-25
+---
+
+# How to create a merge request (MR)
+
+You have already implemented an improvement to the current code base or intend to? Awesome 😎
+Here are some instructions, on how to to that:
+
+- First, make sure you have read the basics of how to contribute
+- Read the following instructions:
+
+There are several ways to create a merge request within GitLab, which are explained in detail in the [official GitLab docs](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html).
+
+However, we will highlight the workflow, we prefer - but feel free to make your own choice.
+
+## Preferred merge request workflow
+This is the first and preferred way to make a merge request, as it is similar to our previous UNICADO workflow. 
+
+Let's assume you have your own (local) feature branch, where you are developing a new feature. And let's further assume, you have forked this branch from the current main or develop branch. If not, you can do it now:
+
+``` { .sh .copy }
+git checkout develop
+git pull origin develop
+git checkout -b <new-branch-name>
+```
+
+*(Of course you can also perform the git operations via your tool of choice, e.g. VSCode)*
+
+If you are working on this branch locally, and it is not shared with remote ☁️, then you have to push it ⏫ to remote, first in order to create a merge request. You can do that as simple as:
+
+``` { .sh .copy }
+git push origin <new-branch-name>
+```
+
+On the gitlab page of the repository in the left sidebar select **Code > Merge request** and select **New merge request**
+
+- For **Source branch** select your branch `<new-branch-name>`
+- For **Target branch** select in this case `develop`
+- Select **Compare branches and continue**
+- Fill out the description (check out the [commit rules](#commitrules) beforehand!)
+- Enter a **Reviewer**
+- Add labels
+- **Create merge request**
+
+!!! note 
+    Choose to delete the remote branch after merge, to keep remote clean
+
+!!! note 
+    Choose squash as merge strategy, to keep the git history streamlined
+
+
+Then you have to wait for the **Merge request pipeline** to pass ✅ (and hopefully not fail🤞) and for the **reviewer** to approve 👍 the request. In case you need to commit adaptions, check the [commit rules](#commitrules) again!
+
+Afterwards on the page of the merge request, you can click on **merge**. Then your feature branch will be automatically merged into the remote branch of `develop` (in this example).
+
+!!! note 
+    As a reviewer, **don't close** the merge request. It will be closed automatically, when the merge is completed.
+
+## Commit rules and messages {#commitrules}
+
+- Commit messages should be clear and concise.
+- Use **English** language.
+- Use the `#` to close and refer to issues. 
+- Please use **present tense** to express what the commit does.
+- **Don't** commit code which you know is not working.
diff --git a/docs/developer/review-merge-request.md b/docs/developer/review-merge-request.md
new file mode 100644
index 0000000..5e0cc09
--- /dev/null
+++ b/docs/developer/review-merge-request.md
@@ -0,0 +1,28 @@
+---
+title: How to review a merge request
+summary: Explains how to review a merge request.
+authors:
+    - Maurice Zimmnau
+    - Kristina Mazur
+date: 2024-09-25
+---
+
+# How to review a merge request
+
+Your colleagues have improved the code and would like you to check it? Nice 😎
+
+If you are GitLab beginner, this is our suggested workflow for a review:
+
+1. Read the [official GitLab documentation](https://docs.gitlab.com/ee/tutorials/reviews/). It includes a ver recommended tutorial :fire: and gives some general inside what is important in an review (checking related issues, examine each file in depth etc.). 
+2. Check the testing pipelines. If tests fail, you and the developer need to decide what to do. The pipelines are also explained in detail in the [testing documentation](testing.md).
+3. Make suggestions for improvement. The recommended and easiest :point_up: way is to open the secondary menu of the merge request, select **Changes** and add a comment to a specific line. A :cool: feature is the **Insert suggestion** - this enables the developer to directly include the change in the web interface!
+
+But sometimes you want to test some code change suggestions locally - here are some short instructions. But it is pretty straight-forward: as the feature branch, which includes the changes, is remote, you can assess it.
+
+``` { .sh .copy }
+git fetch
+git checkout <new-branch-name>
+```
+
+!!! note 
+    You can also push these changes and add them to the merge request. However, it is **not** recommended as the developer does not directly see your implementations as changes, but as an update
\ No newline at end of file
diff --git a/docs/developer/testing.md b/docs/developer/testing.md
index 45a0f45..d6206b7 100644
--- a/docs/developer/testing.md
+++ b/docs/developer/testing.md
@@ -3,7 +3,8 @@ title: Testing Guidelines
 summary: How to test in UNICADO
 authors:
     - Kristina Mazur
-date: 2024-08-05
+    - Maurice Zimmnau
+date: 2024-10-23
 ---
 ## Introduction
 
diff --git a/mkdocs.yml b/mkdocs.yml
index 1bb1735..a7b47dc 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -93,7 +93,10 @@ nav:
     - 'getting-started/installation.md'
     - 'getting-started/takeoff.md'
   - 'Developer':
-    - 'How to Contribute': 'developer/contribute.md'
+    - 'How to Contribute': 
+      - 'Basics': 'developer/contribute.md'
+      - 'How to create a merge request' : 'developer/merge-request.md'
+      - 'How to review a merge request' : 'developer/review-merge-request.md'
     - 'Build Instructions':
       - 'Prerequisites':
         - 'Windows': 'developer/build-environment/windows.md'
-- 
GitLab