Git-Workflow.md

@@ -9,10 +9,11 @@ You can also look at the [Cheat Sheet](Git-Cheat-Sheet) for some quick commands.
 
 ## About this Repository
 
-First of all, a few things about this repo:
+By navigating to our [Gitlab instance](https://git.skywarder.eu/avn/swd/skyward-boardcore/) from a browser, you have access to a couple important pages that you should be familiar with, as a developer:
 
-* In the Files section you can find the build system (`sbs`), the code (in `src/`) and external libraries (in `libs/`).
-* The **Issues** section contains all the issues/enhancements that have to be discussed together. If you find a bug/problem, that's the right place to post it.
+* In the [Files](https://git.skywarder.eu/avn/swd/skyward-boardcore/-/tree/main) page you'll find the build system (`sbs`), the source code files (in `src/`) and external libraries (in `libs/`) of this project.
+* The [Issues](https://git.skywarder.eu/avn/swd/skyward-boardcore/-/issues) page is a sort of todo-list for developers. If you find a bug, or notice a possible improvement, that's the right place to report it.
+* The [Merge Request](https://git.skywarder.eu/avn/swd/skyward-boardcore/-/merge_requests) page contains all the new features that are being added to the codebase, but are not ready to be merged yet.
 
 ## Our Branching Model
 
@@ -32,10 +33,11 @@ To make changes to the software you should use **temporary branches**, such as:
 
 Once the coding is done, the branch will be merged and then deleted.
 
-### Branch Workflow
+### Development Workflow
 
 - A new feature is required (e.g. a barometer driver)
-- A new branch called `barometer-dev` is created from `main` (you can do it locally)
+  - An issue is created for that feature and assigned to a developer
+- Developer creates a new branch called `barometer-dev` from `main` (locally)
 
 ```
 git pull
@@ -48,22 +50,28 @@ git checkout -b barometer-dev
 <modify files>
 git status
 git add name-of-modified-file
-git commit -m "[BAROMETER] Added barometer driver."
+git commit
 ```
 
 - Frequently `git pull` and `git rebase main` to keep aligned to the main branch.
+- You might also want to [push](https://devconnected.com/how-to-push-git-branch-to-remote/) your development branch to the gitlab repository, to be sure it's always accessible and progess doesn't get lost.
 
 ### Merge Requests
 
-When you have created the temporary branch and written the code you will need to follow these steps:
+Once you deem the code ready, it's time to **merge** it:
 
 * Make sure your branch is 0 commits behind main and **TEST** it one last time.
-* Make a `merge request` to merge the branch back into the main branch and set the current IPTL as the reviewer.
+  * If it's not, `git pull && git rebase main`
+* Create a [merge request](https://git.skywarder.eu/avn/swd/skyward-boardcore/-/merge_requests/new) to merge the branch back into the main branch
+  * Set someone (if in doubt, the current IPTL) as reviewer
+  * Cite the relevent issue(s) number in the MR description, if there's any
+  * Mark the MR as `Draft` if it's not quite ready yet (e.g you want someone to review your code but you still have to run some additional tests before merging)
 * If some **issues** are open in the merge request, you will need to **solve** all of them before obtaining the approval from the reviewer.
-* In case you find an issue regarding a whole another topic, it would be best **opening an issue, another branch** and the corresponding merge request.
+* In case you find an issue regarding a whole other topic while developing your feature, it's better if you evelop it separately (another branch & another MR) and mark your MR as draft , so that it doesn't get merged until the issue is fixed
 * Temporary branches should be as "atomic" as possible. This means that the only connection that they have should be the main branch and **NOT** other temporary branches.
 * Once the code is ready and the reviewer likes it, contact your IPTL to approve the merge request.
-* Finally, when ready to merge 99% of the times you will need to squash (aggregate) the commits you made (to not fill the main branch history with minor details) but, if this is not the case and you need to leave more than one commit message, then you should refer to an interactive rebase.
+* Finally, you should clean up the git history: 99% of the times, what you want is to squash all commits (i.e. all your commit end up in a single commit).
+  * If this is not the case, you still need to make sure the git history is clean (minimal number of commits), i.e. no commit fixing up the commit before, no `commit #1: start doing this`, `commit #2: continued doing this`, ecc
 
 ## Commits
 
@@ -74,7 +82,7 @@ Some simple rules:
 1) Write **meaningful commit messages**, with a short explanation on the top and a more specific one under:
 
    ```
-   [Topic] short message
+   [Topic] short message (typically 50 chars max)
    *Blank line*
    Long explanation
    ```
@@ -101,7 +109,11 @@ Some simple rules:
 
 ## **Interactive Rebase**
 
-**:warning: WARNING: Keep in mind that this is ADVANCED stuff and that you should NEVER try to rewrite the main branch history**
+**:warning: WARNING: This is an advanced topic, skip it if you're not familiar with git yet**
+
+---
+
+**:warning: WARNING: You should NEVER try to rewrite the main branch history**
 
 ---