# sandbox

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**

---

# 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