README.md

@@ -1,6 +1,148 @@
-# CAROS
-# _C_ar _R_ealtime _O_perating _S_ystem.
+# CaROS
+# Car Realtime Operating System.
 
 A yocto base distro for DIY car radio
 
-the CaROS specific software is found in meta-caros
+The CaROS specific software is found in meta-caros
+
+
+## Description
+
+
+## Setup
+
+### Preliminaries
+
+Install required packages:
+
+- podman
+
+### Get yocto-build
+```shell
+git clone git@git.larsniesen.de:caros/caros.git
+```
+
+### User Namespace Mapping
+
+Ensure, that /etc/subgid and /etc/subuid contain corresponding
+and sane entries for your account (podman run user).
+If not you might need to run the following setup script (requires restart):
+```shell
+$ sudo ./dev/AddUserToSubgidAndSubuid.sh
+```
+
+## Start development build container
+
+```shell
+$ ./dev/bootstrap.sh [--deploy] [--sstate]
+```
+
+By adding the parameter --deploy, bootstraph.sh maps a deploy folder into the build container.
+Built RPMs will be placed in this folder.
+
+The parameter --sstate maps the build cache directory. This allows the cache to be preserved when the container
+is closed thus significantly reducing build time.
+
+You will end up in the yocto build container as user yocto e.g.:
+
+```shell
+[yocto@1453b5f0ab01 build]$
+```
+
+
+
+## Collaboration
+
+
+
+### Working with branches
+
+Every contributor should use his/her initials (eg. Max Mustermann uses 'mm') as the branch prefix.
+After the prefix comes the issue ID and a short name describing the work.
+
+The branch of Max Mustermann regarding the issue "#13 Integrate Fancy UI into the new web server"
+should be named:
+
+```
+mm/13-integrate-new-web-ui
+```
+
+### Pull requests
+
+The pull request is to be opened **after** testing the branch feature.
+The exception to this are draft PRs
+
+Before merging each PR needs to be reviewed from at least one other contributor
+
+### Merging
+
+Merges are to be done the following:
+
+1. Update main.
+```
+$ git pull origin
+```
+2. Rebase main onto your feature branches.
+    In your feature branch do:
+
+```
+$ git rebase origin/main
+```
+
+3. Test Again if the rebase broke something.
+4. Squash your commits into one.
+```
+$ git rebase -i HEAD~<num of commits>
+```
+In the now open editor replace `pick` with `squash` on all of your commits except the first.
+After that quit the editor and another editor should pop up. Now enter the new commit message.
+The commit message should look like this:
+```
+<issue id>: Description
+```
+For the above example it would be:
+```
+13: Integrate the new web-UI to improve the experience for new users.
+```
+The Description should be **why** the commit was made and not **what** the commit does.
+
+5. Now we add the hash at the start of the commit with:
+```
+git commit --amend -m "#13: Integrate the new web-UI to improve the experience for new users."
+```
+The amend flag lets you _change_ your last commit message. You have to enter your complete commit message but with a hash at the start.
+
+6. Now force push your branch to the remote.
+
+```
+$ git push --force
+```
+7. Fast-forward merge on GitLab without merge commit.
+
+
+For those who are not comfortable with git rebase please follow these steps.
+It is still recommended to do the squashing on the terminal.
+
+
+1. Update main.
+```
+$ git pull origin/main
+```
+
+2. Rebase main onto your feature branches.
+    In your feature branch do:
+
+```
+$ git rebase origin/main
+```
+
+3. Test Again if the rebase broke something.
+
+4. Now force push your branch to the remote.
+
+```
+$ git push --force
+```
+
+5. In the PR now fast-forward merge with squashing and without merge commit.
+