Finalizes documentation for basic gitea/jenkins setup

README.md

@@ -1,6 +1,230 @@
 # sandbox
 
-jenkins testing repobranch protection test
+Test- und Beispiel-Repository für einen lokalen Dev-Platform-Stack mit:
 
+- **Gitea 1.22.x**
+- **Jenkins Multibranch Pipeline**
+- **Webhook-Trigger von Gitea nach Jenkins**
+- **C++/CMake/Ninja Build**
+- **PR Policy Checks**
+- **Docker-basierter CI-Agent**
 
-branch main protection test
+---
+
+# Aktueller Funktionsumfang
+
+Dieses Repository und das zugehörige Jenkins/Gitea-Setup können aktuell:
+
+## SCM / Repository
+- Repository in **Gitea** hosten
+- Änderungen per **Git Push** empfangen
+- **Pull Requests** in Gitea verwalten
+- Webhooks von Gitea an Jenkins senden
+
+## Jenkins / CI
+- Jenkins als **Multibranch Pipeline** verwenden
+- Branches und Pull Requests automatisch erkennen
+- Builds durch **Push Events** automatisch starten
+- Build-Status an Gitea zurückmelden
+
+## Build-Umgebung
+- Pipeline-Schritte in einem **Docker-Container** ausführen
+- dafür ein vordefiniertes CI-Image verwenden
+- folgende Tools im CI bereitstellen:
+  - `python3`
+  - `clang-format`
+  - `cmake`
+  - `ninja`
+  - `git`
+  - `g++`
+  - `make`
+
+## C++ Projektbasis
+- minimales Beispielprogramm über `main.cpp`
+- Build mit **CMake**
+- Testausführung über **CTest**
+- Testdateien unter `tests/`
+
+## PR Policy Checks
+Für geänderte C/C++-Dateien werden in der CI geprüft:
+
+- `.clang-format` muss im Repository vorhanden sein
+- geänderte C/C++-Dateien müssen mit `clang-format` konform sein
+- zu geänderten C/C++-Dateien muss ein passender Test unter `tests/` oder `test/` vorhanden sein
+- Vergleich gegen den Zielbranch erfolgt robust über Git-Refs wie z. B.:
+  - `origin/main`
+  - `main`
+
+---
+
+# Repository-Struktur
+
+Beispielhaft verwendete Dateien:
+
+```text
+.
+├── .clang-format
+├── CMakeLists.txt
+├── Dockerfile.ci
+├── Jenkinsfile
+├── README.md
+├── ci/
+│   └── check_pr_policies.py
+├── main.cpp
+└── tests/
+    └── test_main.cpp
+```
+
+---
+
+# CI / Jenkins Pipeline
+
+Die Jenkins-Pipeline umfasst aktuell diese Schritte:
+
+1. **Checkout**
+   - Repository aus Gitea auschecken
+   - zusätzliche Fetch-/Submodule-Schritte ausführen
+
+2. **Policy Checks**
+   - `ci/check_pr_policies.py` ausführen
+   - Formatierung und Testbezug prüfen
+
+3. **Configure**
+   - CMake-Buildverzeichnis erzeugen
+
+4. **Build**
+   - Projekt mit CMake/Ninja bauen
+
+5. **Test**
+   - Tests über `ctest` ausführen
+
+6. **Cleanup**
+   - Workspace am Ende bereinigen
+
+---
+
+# Docker-basierter CI-Agent
+
+Die Pipeline verwendet ein vorbereitetes Docker-Image statt bei jedem Lauf ein neues Build-Image zu erzeugen.
+
+## Beispiel
+Das Image wird lokal/auf dem Build-Host gebaut:
+
+```bash
+docker build -t lifemaps/ci-cpp:latest -f Dockerfile.ci .
+```
+
+Danach nutzt Jenkins dieses Image als Agent.
+
+## Vorteile
+- schnellere PR-Builds
+- reproduzierbare Toolchain
+- keine langen `apt install`-Phasen pro Build
+- saubere Trennung zwischen Jenkins-Controller und Build-Umgebung
+
+---
+
+# Branch- und PR-Workflow
+
+Der aktuelle Workflow unterstützt:
+
+- Arbeiten auf Feature-Branches
+- Öffnen von Pull Requests gegen `main`
+- automatisches Bauen von PRs
+- Rückmeldung des Build-Status an Gitea
+
+Empfohlen ist:
+
+- keine direkten Änderungen auf `main`
+- Änderungen über Feature-Branch + Pull Request
+- Merge erst nach erfolgreichem CI-Lauf
+
+---
+
+# Lokales Arbeiten
+
+## Formatierung prüfen
+```bash
+clang-format --dry-run --Werror main.cpp tests/test_main.cpp
+```
+
+## Formatierung anwenden
+```bash
+clang-format -i main.cpp tests/test_main.cpp
+```
+
+## CI-Policy lokal testen
+```bash
+python3 ci/check_pr_policies.py
+```
+
+## Build lokal ausführen
+```bash
+cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug
+cmake --build build --parallel
+ctest --test-dir build --output-on-failure
+```
+
+---
+
+# Voraussetzungen auf Jenkins-Seite
+
+Für das Setup werden u. a. folgende Jenkins-Plugins benötigt:
+
+- `docker-workflow`
+- `pipeline-model-definition`
+- `workflow-scm-step`
+- `workflow-cps`
+- `ws-cleanup`
+- `gitea`
+- `git`
+- `git-client`
+- `scm-api`
+- `workflow-multibranch`
+
+Zusätzlich muss der Jenkins-Container Zugriff auf Docker haben, z. B. über:
+
+- Docker CLI im Jenkins-Container
+- Mount von `/var/run/docker.sock`
+
+---
+
+# Webhook / Automatischer Trigger
+
+Gitea ist so konfiguriert, dass **Push Events** an Jenkins gemeldet werden.
+
+Beispiel-Endpunkt:
+
+```text
+https://jenkins.life-maps.com/gitea-webhook/post
+```
+
+Damit können:
+- neue Branch-Commits
+- PR-bezogene Änderungen
+- Status-Updates
+
+automatisch Jenkins-Builds auslösen.
+
+---
+
+# Beispielziel des Repositories
+
+Dieses Repository dient aktuell als:
+
+- Referenz für Jenkins/Gitea-Integration
+- Testumgebung für PR-Policies
+- Minimalbeispiel für C++/CMake-basierte CI
+- Grundlage für spätere Erweiterungen, z. B. mit Qt
+
+---
+
+# Status
+
+Aktuell ist das Setup geeignet für:
+
+- Jenkins/Gitea-Webhook-Integration
+- Pull-Request-basierte CI
+- C++/CMake/Ninja Beispielprojekte
+- Policy-basierte Qualitätsprüfungen im PR-Prozess
+- Vorbereitung auf weitergehende Qt-Migrations- und CI-Themen