diff --git a/docs/assets/images/merge-request.jpg b/docs/assets/images/merge-request.jpg
deleted file mode 100644
index 185c647a15bed835dcb1de20787a19b81115363c..0000000000000000000000000000000000000000
--- a/docs/assets/images/merge-request.jpg
+++ /dev/null
@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:1dd84696fef1daad6bb4699fb0f4f6d972cc8de985b5c6b5eaa5972a3dd24d30
-size 74293
diff --git a/docs/assets/images/merge_request_workflow.png b/docs/assets/images/merge_request_workflow.png
new file mode 100644
index 0000000000000000000000000000000000000000..0a2a9590acf078fb7ed52809a56a95225ade5560
--- /dev/null
+++ b/docs/assets/images/merge_request_workflow.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:16cb99407e055542adabfb9a2ed30cfd5342bcba8455fbf1a89e0bb5a2e101a9
+size 564863
diff --git a/docs/get-involved/build-environment/windows.md b/docs/get-involved/build-environment/windows.md
index d2bea3d34a533cd1449547d107321f222a9c6983..e6ad8940172254a4a34604279ebedc507ec3a8d1 100644
--- a/docs/get-involved/build-environment/windows.md
+++ b/docs/get-involved/build-environment/windows.md
@@ -5,36 +5,36 @@ authors:
- Sebastian Oberschwendtner
date: 2024-03-01
---
+
## Introduction
-We recommend to use the Windows compiler for the best experience and to create programs which are easily distributable to other Windows machines.
+We recommend using the Windows compiler for the best experience and to create programs that are easily distributable to other Windows machines.
The tools used are:
- Compiler: `Clang` or `MSVC`
- Generator tool: `CMake` (more infos [here](../build/general.md))
- Package manager: `vcpkg`
-- some other tools (Python, Git - see below)
+- Some other tools (Python, Git - see below)
->You can use _Visual Studio Code_ as your IDE which will integrate everything, but since we are not prescribing any IDE, this will only show you how to setup the build tools. :point_up:
+> You can use _Visual Studio Code_ as your IDE which will integrate everything, but since we are not prescribing any IDE, this will only show you how to set up the build tools. :point_up:
---
## Install Git
-- Download and Install the latest release of **Git**: [Download Git :octicons-link-external-16:](https://git-scm.com/download/win){:target="_blank"}
-- Enable the option to make **Git** available in *PATH*.
-- Leave the rest of the options to their defaults.
+- Download and Install the latest release of **Git**: [Download Git ](https://git-scm.com/download/win)
+- Follow [Install and Configure Git](../../get-involved/contributor-tutorial/git-installation&configuration.md) for a detailed explanation of how to install & configure Git.
---
## Install Python
-- Download and install **Python**: [Download Python :octicons-link-external-16:](https://www.python.org/downloads/windows/){:target="_blank"}
+- Download and install **Python**: [Download Python ](https://www.python.org/downloads/windows/)
!!! warning
- Please install version **3.11.8**, select all the default options and check the option to add Python to *PATH* & make sure to include the debug binaries!
+ Please install version **3.11.8**, select all the default options, and check the option to add Python to *PATH* & make sure to include the debug binaries!
### Python Dependencies
-The only Python dependency we have is `pipenv` which is used to manage the Python environment.
+The only Python dependency we have is `pipenv`, which is used to manage the Python environment.
Install it by executing the following command in a terminal after you have **successfully** installed Python:
```{.sh .copy}
@@ -44,7 +44,7 @@ pip install pipenv
---
## Install CMake
-- Download and Install the latest release of **CMake**: [Download CMake :octicons-link-external-16:](https://cmake.org/download/){:target="_blank"}
+- Download and Install the latest release of **CMake**: [Download CMake ](https://cmake.org/download/)
!!! important
Install at least version **3.29**!
@@ -54,18 +54,19 @@ pip install pipenv
---
## Install VS Code (optional)
-If you'd like to use VS Code as your IDE and haven't installed it yet, now it's the right time for it :clock:
-You can download it from the official website: [Download Visual Studio Code :octicons-link-external-16:](https://code.visualstudio.com/Download)
-Afterwards, you can freely decide on installing nice extensions as:
- - C/C++, C/C++ Extension Pack, C/C++ Themes: for a convenient working environment in C++
- - CMake, CMake Tools: for build process within your IDE
- - cpp-check-lint: for style checks during coding
- - ...
+If you'd like to use VS Code as your IDE and haven't installed it yet, now is the right time :clock:.
+You can download it from the official website: [Download Visual Studio Code ](https://code.visualstudio.com/Download)
+
+Afterwards, you can freely decide on installing nice extensions such as:
+- C/C++, C/C++ Extension Pack, C/C++ Themes: for a convenient working environment in C++
+- CMake, CMake Tools: for build process within your IDE
+- cpp-check-lint: for style checks during coding
+- ...
---
## Install Build Tools
-- Download the build tools from Microsoft: [Download Build Tools :octicons-link-external-16:](https://visualstudio.microsoft.com/downloads/?q=build+tools#build-tools-for-visual-studio-2022){:target="_blank"}
+- Download the build tools from Microsoft: [Download Build Tools ](https://visualstudio.microsoft.com/downloads/?q=build+tools#build-tools-for-visual-studio-2022){:target="_blank"}
The page should look something like this:
@@ -76,19 +77,19 @@ The page should look something like this:
- *C++ Clang tools for Windows* (⇒ This will include the Clang compiler as well.)
!!! attention
- The latest version of Visual Studio Build Tools can change throughout time. Just download the latest one and keep a note which version that is.
+ The latest version of Visual Studio Build Tools can change over time. Just download the latest one and keep a note of which version that is.
---
## Install vcpkg
-*vcpkg* is the open-source package manager maintained by Microsoft we use to install and manage our dependencies.
+*vcpkg* is the open-source package manager maintained by Microsoft that we use to install and manage our dependencies.
-- *vcpkg* recommends to keep the path where you install it short, so create the following folder:
+- *vcpkg* recommends keeping the path where you install it short, so create the following folder:
:octicons-file-directory-16: `C:\dev`
!!! warning
- From now on we assume, that you installed *vcpkg* in this folder!
+ From now on, we assume that you installed *vcpkg* in this folder!
- Open a terminal inside `C:\dev`
- Clone the *vcpkg* repository:
@@ -99,15 +100,31 @@ git clone https://github.com/microsoft/vcpkg.git
- Create the *vcpkg* executable by executing this command in the opened terminal:
-```{.cmd .copy}
-.\vcpkg\bootstrap-vcpkg.bat
-```
+=== "Windows"
-You can get more information how *vcpkg* can be installed in the [Readme :octicons-link-external-16:](https://github.com/microsoft/vcpkg/?tab=readme-ov-file#getting-started){:target="_blank"} of the project itself.
+ ``` { .cmd .copy }
+ .\vcpkg\bootstrap-vcpkg.bat
+ ```
+ !!! note
+ This may take some time, and you can install one package after the other.
+=== "MinGW"
+
+ ``` { .sh .copy }
+ cmd.exe /c .\vcpkg\bootstrap-vcpkg.bat
+ ```
+
+To check if *vcpkg* is installed on your system, you can run the following command in your terminal or command prompt:
+
+```{.cmd .copy}
+vcpkg --version
+```
+If you get an error like `vcpkg: command not found`, it means that *vcpkg* is not properly installed or the executable is not in your system's PATH. Make sure that *vcpkg* is correctly installed and that the path to the executable is included in the environment variables.
+You can get more information on how *vcpkg* can be installed in the [Readme ](https://github.com/microsoft/vcpkg/?tab=readme-ov-file#getting-started) of the project itself.
+---
\ No newline at end of file
diff --git a/docs/get-involved/contribute.md b/docs/get-involved/contribute.md
index 34db46db5fc1336e37f789883739f942f2d0b0f2..8ec14b9abc6e852aa21c9f30dd5242b84a4e450b 100644
--- a/docs/get-involved/contribute.md
+++ b/docs/get-involved/contribute.md
@@ -17,13 +17,14 @@ Awesome! :sunglasses: Please make sure to read our *style guides* first:
## How to actually contribute
This is how you can actually make a difference:
+The flowchart below illustrates the Merge Request workflow, along with the commands used at each stage.
-<figure markdown>
- {width="500"}
+<figure>
+ <img src="../../assets/images/merge_request_workflow.png" alt="merge-request" width="500" style="border: 2px solid black;">
<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:
+You cloned/forked the UNICADO Package successfully acc. to [Get Source Code](get-source-code.md). 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}
@@ -66,6 +67,6 @@ The issues should **not** be used as a *Q/A* forum.
---
-:heart: Thanks for reading this! We are looking forward to your contributions!
+❤️ Thanks for reading this! We are looking forward to your contributions!
UNICADO Team
diff --git a/docs/get-involved/contributor-tutorial/git-installation&configuration.md b/docs/get-involved/contributor-tutorial/git-installation&configuration.md
new file mode 100644
index 0000000000000000000000000000000000000000..5fb414b328e905c2db6fd4a06b9d1b87c5232d57
--- /dev/null
+++ b/docs/get-involved/contributor-tutorial/git-installation&configuration.md
@@ -0,0 +1,139 @@
+---
+title: Install & Configure Git on Windows
+summary: Explains how to download, install & configure Git.
+authors:
+ - Alfin Johny
+date: 2024-12-05
+---
+
+### Download & Install Git
+
+<span style="color:rgb(68, 0, 255);">🎥</span> **If you'd rather skip the text explanations below, watch this video tutorial. [Git_Installation&Configuration](/docs/get-involved/contributor-tutorial/videos/Git_Installation&Configuration.mp4)**.
+
+To begin, download and install Git for Windows from the official [Git website](https://git-scm.com/download/win). You will be provided with an installer file that has a `.exe` extension. Locate the downloaded file in your `Downloads` folder and double-click it to start the installation process. Follow the prompts in the installation wizard. While most of the default options are suitable, make sure you select **Git from the command line and also from 3rd-party software**, so Git is accessible from your terminal/command prompt. Once installed, Git will be added to the System Environment Path variable, making it accessible globally.
+
+After installation, open the Git terminal and verify the installation by typing the following command:
+
+```{ .cmd .copy }
+git --version
+```
+
+This should return the installed version of Git, confirming that Git is set up correctly.
+
+---
+
+### Configure Git
+
+Once Git is installed, configure your user name and email, which will be associated with your commits. Run the following commands in the terminal to set these configurations:
+
+```{ .cmd .copy }
+git config --global user.name "Your Name"
+git config --global user.email "your.email@example.com"
+git config --list # Check if the configuration was successful
+```
+
+This setup ensures that your commits are correctly attributed to your identity.
+
+Now you're ready to start using Git for version control!
+
+
+
+### SSH Configuration for GitLab
+
+To securely connect with the UNICADO project hosted on GitLab and access its repositories, you'll need to set up SSH keys. Follow the steps below to generate a new SSH key pair, configure an SSH agent, create an SSH config file (optional), and test the SSH connection.
+
+
+#### Step 1: Generate an SSH Key Pair
+
+Open a terminal and run the following command to generate a new SSH key pair. Replace the email with the one associated with your GitLab account:
+
+```{ .cmd .copy }
+ssh-keygen -t ed25519 -C "your.email@example.com"
+```
+
+- `-t ed25519`: Specifies the key type. ED25519 is the recommended key type for SSH.
+- `-C "your.email@example.com"`: Adds a comment (usually your email) to the key.
+
+When prompted, press Enter to save the key to the default location (`C:\Users\YourName.ssh\id_ed25519` on Windows). You can also specify a different file name or path if desired. Optionally, set a passphrase for extra security (recommended but not required).
+
+---
+
+#### Step 2: Create an SSH Config File (Optional but Recommended)
+
+If you use multiple SSH keys (for different services like GitHub, GitLab, etc.), it's a good idea to create an SSH config file for easier management. Open the SSH config file using notepad and
+
+```{ .cmd .copy }
+notepad C:\Users\<YourUsername>\.ssh\config
+```
+
+Replace <YourUsername> with your actual Windows username. This will open the config file in Notepad (or create it if it doesn't exist).
+
+```{ .cmd .copy }
+Host gitlab.com
+ User git
+ HostName gitlab.com
+ PreferredAuthentications publickey
+ IdentityFile C:\Users\<YourUsername>\.ssh\id_ed25519
+```
+
+- `Host`: An alias for the connection (use `gitlab.com` to match the GitLab domain).
+- `User`: The SSH user for GitLab (`git`).
+- `HostName`: The GitLab domain (`gitlab.com`).
+- `PreferredAuthentications`: Specifies that public key authentication should be used.
+- `IdentityFile`: The path to your private SSH key (default is `.ssh\id_ed25519`).
+---
+
+#### Step 3: Add SSH Key to SSH Agent
+
+The SSH agent manages your private keys, so you won’t need to enter your passphrase every time you interact with GitLab. Start the SSH agent by running:
+
+```{ .cmd .copy }
+ssh-agent bash
+```
+
+On Windows command prompt, the SSH agent may be automatically set up. Add your private key to the agent:
+
+```{ .cmd .copy }
+ssh-add C:\Users\<YourUsername>\.ssh\id_ed25519
+```
+
+If you used a different name or location for your key (e.g., `id_rsa_gitlab`), adjust the path accordingly:
+
+```{ .cmd .copy }
+ssh-add C:\Users\<YourUsername>\.ssh\id_rsa_gitlab
+```
+
+---
+
+#### Step 4: Add SSH Key to GitLab
+
+GitLab uses SSH to authenticate your identity when interacting with repositories. To set up SSH authentication, you'll need to add the public key to your GitLab account.
+
+First, copy the public key to your clipboard. On Windows (with Git Bash), use the following command to display the public key:
+
+```{ .cmd .copy }
+cat .ssh\id_ed25519.pub
+```
+
+Next, log in to your GitLab account and navigate to your **Profile Settings**. In the left sidebar, select **SSH Keys**, paste the public key into the **Key** field, and optionally provide a title (e.g., "My Laptop"). Click **Add key** to save it.
+
+---
+
+#### Step 5: Test the SSH Connection
+
+Test whether your SSH key is set up correctly by running the following command:
+
+```{ .cmd .copy }
+ssh -T git@gitlab.com
+```
+
+If the key is set up properly, the output should say:
+
+```
+Welcome to GitLab, @yourusername!
+```
+
+If it’s your first time connecting, GitLab may ask you to confirm the authenticity of the host. Type `yes` to proceed.
+
+By following these steps, you’ve successfully configured SSH for GitLab. You can now securely interact with GitLab repositories over SSH, enabling you to clone, push, and pull using your private key.
+
diff --git a/docs/get-involved/contributor-tutorial/videos/Git_Installation&Configuration.mp4 b/docs/get-involved/contributor-tutorial/videos/Git_Installation&Configuration.mp4
new file mode 100644
index 0000000000000000000000000000000000000000..cb4268bda5a0546a020edef2d02fd8e2afce1031
Binary files /dev/null and b/docs/get-involved/contributor-tutorial/videos/Git_Installation&Configuration.mp4 differ
diff --git a/docs/get-involved/contributor-tutorial/videos/Merge_Request_Workflow.mp4 b/docs/get-involved/contributor-tutorial/videos/Merge_Request_Workflow.mp4
new file mode 100644
index 0000000000000000000000000000000000000000..d443dddb6d74d0ef60e400fd74d6ce3651cf8661
Binary files /dev/null and b/docs/get-involved/contributor-tutorial/videos/Merge_Request_Workflow.mp4 differ
diff --git a/docs/get-involved/contributor-tutorial/videos/SSH_Configuration.mp4 b/docs/get-involved/contributor-tutorial/videos/SSH_Configuration.mp4
new file mode 100644
index 0000000000000000000000000000000000000000..21a747114d1ad4c1351181de906b9d96e5ec8d43
Binary files /dev/null and b/docs/get-involved/contributor-tutorial/videos/SSH_Configuration.mp4 differ
diff --git a/docs/get-involved/get-source-code.md b/docs/get-involved/get-source-code.md
index c15decdfabee5bcf125ec27978cdf0d95e6758d2..188a591e6d346f12d468f68fc79d76382fb28b01 100644
--- a/docs/get-involved/get-source-code.md
+++ b/docs/get-involved/get-source-code.md
@@ -5,40 +5,86 @@ authors:
- Sebastian Oberschwendtner
date: 2024-04-09
---
+# Get UNICADO Source Code
+
The source code of **UNICADO** is grouped into different repositories.
You can get an overview of which repository contains which topic [here](../documentation/overview.md).
Whenever one repository needs another repository, we include it as a *Git Submodule*.
-If you are not familiar with *Git Submodules*, please read their [Documentation :octicons-link-external-16:](https://git-scm.com/book/en/v2/Git-Tools-Submodules).
+If you are not familiar with *Git Submodules*, please read their Documentation  <https://git-scm.com/book/en/v2/Git-Tools-Submodules>
-## Get the Source Code
-The repository [:simple-gitlab: Unicado Package :octicons-link-external-16:](https://git.rwth-aachen.de/unicado/unicado-package) contains all necessary source code as submodules to get started compiling **UNICADO** and its installer.
+🎥 **Watch the first part of [Merge Request Workflow](../assets/videos/Merge_Request_Workflow.mp4) video for a more detailed explanation of below mentioned steps**.
-When you clone the repository for the first time use this command:
+## Step-by-Step Guide to Fork Unicado Package Repository on GitLab and update its submodules
-=== "Gitlab"
+The repository [Unicado Package](https://git.rwth-aachen.de/unicado/unicado-package) contains all necessary source code as submodules to get started compiling **UNICADO** and its installer. It is used to create UNICADO releases and provides a good starting point for development. UNICADO project is hosted on GitLab platform. So you need to have a GitLab account if you want to fork the repsitory and start contributing to it.
- ```{.sh .copy}
- git clone --recurse-submodules git@git.rwth-aachen.de:unicado/unicado-package.git
- ```
+**Step 1: Create a GitLab Account**
+
+ - Open your browser and navigate to [GitLab](https://gitlab.com/).
+ - Click on the **"Register"** button and fill in the required fields. Optionally, sign up using **Google** or **GitHub** credentials.
+ - Check your email for a confirmation link, and click on it to verify your account.
+ - Once verified, log in to your GitLab account.
+
+**Step 2: Locate the Repository You Want to Fork**
+
+ Search for the Unicado Package Repository: Use GitLab's **search bar** at the top of the page to find the repository. Click on the repository from the search results to view its main page.
+
+
+**Step 3: Fork the Repository**
+
+ - **Click "Fork":** Find the **"Fork"** button at the top-left of the repository page.
+ - **Select Namespace:** Choose your **Personal** or **Group** namespace.
+ - **Confirm Fork:** Click **Fork project** to create your copy.
+ - **Wait for Completion:** The process will take a few moments, after which you’ll be redirected to your forked repository.
+
+Fork method is used for contributing to a GitLab project when you are not a member of the project with write access. Allows you to freely make changes to your fork and propose changes to the original repository through a merge request (MR).
+Forking Creates a personal copy of a repo on the server, the general format of forked repository is https://gitlab.com/your-username/repo.git. Now if you want to work on the repository locally using an IDE ( for eg. VSC), you need to clone the forked version of Unicado Package Repository to your locall machine. Cloning will create a local copy of Forked repository.
+
+**Step 4: Clone Your Forked Repository**
+
+ - **Navigate to Your Fork:** Navigate to your forked repository in the GitLab dashboard under Projects.
+
+ - **Copy the Clone URL:** Click the Clone button and choose HTTPS or SSH.
-=== "Phabricator"
+ - **Clone the Repository Locally:**
- ```{.sh .copy}
- git clone --recurse-submodules ssh://git@unicado.ilr.rwth-aachen.de:2222/source/rUNICADO.git
+
+
+=== "HTTP"
+
+ ``` { .cmd .copy }
+ git clone https://gitlab.com/your-username/repository-name.git
```
- !!! note
- *Phabricator* is deprecated it will be removed in the near future!
+
+=== "SSH"
+
+ ``` { .sh .copy }
+ git clone git@gitlab.com:your-username/repository-name.git
+ ```
Should the default branch not yet contain the submodules or you want to update the submodules afterwards, you can do that with:
-```{.sh .copy}
-git submodule update --init --recursive
-```
-!!! warning
- Only proceed when all submodules could be checked out successfully. Otherwise the builds will not work!
+ ```{.cmd .copy}
+ git submodule update --init --recursive
+ ```
+
-## Where to find what
-In the following instructions we assume, that you cloned the **Unicado Package** as described.
+>⚠️You can push to a forked repository without configuring SSH by using HTTPS for authentication instead of SSH. However, SSH is often preferred for its security and ease of use once set up. 🎥**Follow [SSH Configuration](../assets/videos/SSH_Configuration.mp4) tutorial video if you want to set up SSH**.
+
+>⚠️Only proceed when all submodules could be checked out successfully. Otherwise the builds will not work!
+
+In the following instructions we assume, that you forked and cloned the **Unicado Package** as described.
That means, whenever we talk about building inside the *Aircraft Design* folder, we mean the submodule **inside** the **Unicado Package** repository.
-In general, you should find every mentioned directory or file in one of the submodules of the **Unicado Package**. :point_up:
\ No newline at end of file
+In general, you should find every mentioned directory or file in one of the submodules of the **Unicado Package**. :point_up:
+
+**Step 5: Update the Repository with the Latest Changes from Remote**
+
+Once the repository is cloned, you need to update it with the latest changes from the remote. If your repository includes multiple submodules, follow these steps:
+
+ ```{.cmd .copy}
+ git checkout main # Checkout the `main` branch of your repository
+ git fetch # Fetch the latest updates from the remote repository
+ git pull origin main # Pull the latest changes from the remote `main` branch
+
+ ```
diff --git a/docs/get-involved/merge-request.md b/docs/get-involved/merge-request.md
index f62ea7f088f68e8dd0f7dc91a864d03efc7bac65..854283a12b3cb52791b81f77c87f9893892d1697 100644
--- a/docs/get-involved/merge-request.md
+++ b/docs/get-involved/merge-request.md
@@ -9,64 +9,108 @@ 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:
+Follow these steps to create a merge request (MR) from your forked repository:
-- First, make sure you have read the basics of how to contribute
-- Read the following instructions:
+- First, make sure you have read [How to contribute to UNICADO](../get-involved/contribute.md)
+- Then, proceed with the steps below:
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
+## Preferred Merge Request Workflow for a Forked Repository
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 forked( if you are not a direct member of UNICADO project) and cloned the Unicado Package repoistory and updated all it's submodules following [Get Source Code](get-source-code.md ). Open your preferred IDE (e.g., Visual Studio Code). Ensure that Git is integrated within your IDE. Most IDEs, such as VSCode, have built-in Git integration. Go to the sub module where you want to make the change. Create your own (local) branch, where you are developing a new feature / fixing bug / addong documentation.
+For a more detailed explanation of the steps mentioned below, watch the [Merge Request Workflow](../assets/videos/Merge_Request_Workflow.mp4) video.
-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:
+### 1. Configure Remotes:
-``` { .sh .copy }
-git checkout develop
-git pull origin develop
-git checkout -b <new-branch-name>
+Verify and set up remotes for your fork and the upstream repository:
+
+```{ .cmd .copy }
+git remote -v
+```
+Add the original UNICADO repository as the upstream remote:
+
+```{ .cmd .copy }
+git remote add upstream git@gitlab.com:unicado/unicado.git
```
-*(Of course you can also perform the git operations via your tool of choice, e.g. VSCode)*
+### 2. Create a New Branch
+
+Create a new branch from `main` to work on your feature or bug fix. The `main` branch contains the stable version of the code and ‘main’ is the default branch (i.e., the branch you check out when cloning the repository). Developers are not allowed to push directly to this branch. All changes must go through <new-branch-name> branch and a merge request process.
+
+```{ .cmd .copy }
+git checkout -b <new-branch-name> # Create a new branch
+```
+Where <new-branch-name> is the branch where developers work on new features or bug fixes. Each developer creates their own branch from the `main` branch. After completing changes on the new branch, a Merge Request (MR) is created to merge the changes into the `main` branch. Once the MR is reviewed and approved, it gets merged into `main`.
+
+Make sure your branch name follows this convention:
+
+- `feature/your-feature` # Changes which brings in new feature
+- `bugfix/your-bugfix` # Changes which fixes bug
+- `documentation/your_documentation` #Changes which adapt existing documentation / Adding new documentation.
+
+This ensures your branch can be pushed successfully.
+
+### 3. Make Changes
+
+Modify the submodule files as needed.
+
+### 4. Stage and Commit Your Changes
+
+After making your changes, stage them using the `git add` command:
+
+```{ .cmd .copy }
+git add . # Stage all modified files
+```
+
+Next, commit your changes with a meaningful commit message:
+
+
+#### Guidelines for a Good Commit Message
+
+- **Title**: A short description of what the commit does (use present tense).
+- **Body**: Explain why and how the change was made. Include any relevant details, such as specific files changed or issues addressed. Should be clear and concise. Use **English** language.
+- **Reference**: Mention related issues or tickets (if applicable). Use the `#` to close and refer to issues.
+
+Before committing, ensure that your code is working as expected by running local tests (such as static code analysis) and avoid committing code that is not functioning properly.
+
+### 5. Push Changes to Your Fork
-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:
+Push your branch to your forked repository on GitLab:
-``` { .sh .copy }
+```{ .cmd .copy }
git push origin <new-branch-name>
```
-!!! note
- Please be aware that your branch name **must** follow this naming convention: `feature/some-feature`, `bugfix/some-bugfix` or `documentation/some_documentation`. Otherwise you will not be able to push it.
+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.
-On the gitlab page of the repository in the left sidebar select **Code > Merge request** and select **New merge request**
+### 6. Create a Merge Request (MR) to the Original Repository
-- 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**
+To propose your changes to the original UNICADO repository:
-!!! note
- Choose to delete the remote branch after merge, to keep remote clean
+1. Go to the original UNICADO repository on GitLab.
+2. Click Create Merge Request.
+3. Set your forked repository's <new-branch-name> as the source branch and `main` in the original repository as the target branch.
+4. Fill out the MR details:
+ - Provide a clear title and description of your changes.
+ - Use the available MR templates for consistency. Select a suitable one from the dropdown menu. These templates are saved in merge_request_templates folder inside .gitlab
+5. Add reviewers who will assess your changes (e.g., project maintainers):
+ - Reviewers will leave comments or request changes.
+ - Make the necessary updates locally, commit them, and push to the same branch. In case you need to commit adaptions, check the [Guidelines for a Good Commit Message](#guidelines-for-a-good-commit-message) again!
+6. After pushing your branch, the Continuous Integration (CI) pipeline will run automatically for the MR. CI checks ensure that your code meets the project’s quality standards and passes all tests.
+ - Monitor Pipeline Status: Once your MR is created, GitLab will display the pipeline status in the MR. Look for ✅ (success) or ❌ (failure).
+ - Fixing CI Failures: Open the pipeline logs to identify the issue. Fix the problem in your local branch. Commit and push the updates:
-!!! note
- Choose squash as merge strategy, to keep the git history streamlined
+> As a reviewer, don't close the merge request. It will be closed automatically, when the merge is completed.
+> 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!
+### 7. Approval, Merge and clean up
-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).
+The reviewer(e.g., project maintainers) will merge your branch into the main branch. GitLab automatically deletes the source branch(<new-branch-name>) if "Remove source branch" is selected during the merge. Additionally, you can close the related issue, which should have been resolved by the MR.
-!!! note
- As a reviewer, **don't close** the merge request. It will be closed automatically, when the merge is completed.
+By following these steps, you ensure that your contributions are properly tracked, reviewed, and merged with minimal disruption to the project.
-## Commit rules and messages {#commitrules}
+> You can also perform the git operations via your tool of choice, e.g. VSCode
-- 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/mkdocs.yml b/mkdocs.yml
index 1a9778434b1ef5dd3f00ef391ff7a909b77db511..0282aaec330d6d90ecb0e90ef9c5af27319e20dc 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -336,9 +336,18 @@ nav: # Customizes the main navigation struc
- C++: get-involved/style/cpp.md
- Python: get-involved/style/python.md
- Testing Guidelines: get-involved/testing.md
- - How to Contribute: get-involved/contribute.md
- - IDE Setup: get-involved/ide-setup.md
- - Release Package: get-involved/release-package.md
+ - How to Contribute: # Subsection for contribution guidelines.
+ - Basics: 'get-involved/contribute.md'
+ - Code of Conduct: 'get-involved/code-of-conduct.md'
+ - Merge Requests: 'get-involved/merge-request.md'
+ - Review Merge Requests: 'get-involved/review-merge-request.md'
+ - Contributor Tutorial:
+ - Git Installation & Configuration: get-involved/contributor-tutorial/git-installation&configuration.md
+ - Git Installation & Configuration Video: get-involved/contributor-tutorial/videos/Git_Installation&Configuration.mp4
+ - Merge Request Workflow: get-involved/contributor-tutorial/videos/Merge_Request_Workflow.mp4
+ - SSH Configuration : get-involved/contributor-tutorial/videos/SSH_Configuration.mp4
+ - IDE Setup: 'get-involved/ide-setup.md'
+ - Release Package: 'get-involved/release-package.md'
- About: # Top-level item for general site information.
- About us: 'about.md' # Link to the about page.
@@ -348,4 +357,3 @@ nav: # Customizes the main navigation struc
-