tooling: make .junie/.gemini docs-first (remove legacy guidelines)
This commit is contained in:
@@ -0,0 +1,57 @@
|
||||
---
|
||||
modul: workflow-pr-branchschutz
|
||||
status: active
|
||||
last_reviewed: 2025-10-22
|
||||
review_cycle: 180d
|
||||
summary: Empfehlungen für Branchschutz, PR-Ablauf und Naming-Konventionen.
|
||||
yt_epic: MP-1
|
||||
yt_issues: [ ]
|
||||
---
|
||||
|
||||
# Branchschutz & Pull-Request Workflow
|
||||
|
||||
Diese Anleitung beschreibt einen einfachen, robusten Flow für `main` mit kurzen Feature-Branches und klaren
|
||||
Qualitätschecks.
|
||||
|
||||
## 1) Branch-Naming
|
||||
|
||||
- Feature: `feature/<kurz-beschreibung>`
|
||||
- Bugfix: `fix/<kurz-beschreibung>`
|
||||
- Docs: `docs/<kurz-beschreibung>`
|
||||
|
||||
Optional: Issue-Key voranstellen, z. B. `feature/MP-7-doku-konsolidieren`.
|
||||
|
||||
## 2) Pull Request (PR)
|
||||
|
||||
- PR-Titel nach Conventional Commits (kurz): `docs(api): Front‑Matter vereinheitlicht (MP-7)`
|
||||
- Beschreibung kurz mit Bulletpoints; DoD-Checkliste abhaken (Template vorhanden)
|
||||
- CI muss grün sein (Backend + Docs)
|
||||
|
||||
## 3) Branchschutz (GitHub Einstellungen → Branches → main)
|
||||
|
||||
- Require a pull request before merging
|
||||
- Require status checks to pass before merging
|
||||
- aktivieren: `CI Docs`, `CI` (Backend falls vorhanden)
|
||||
- Require linear history
|
||||
- Require approvals: mindestens 1 (bei Solo-Projekt optional, aber empfohlen)
|
||||
- Allow squash merging only
|
||||
- Disallow force pushes, Disallow deletions
|
||||
|
||||
## 4) Commits & YouTrack
|
||||
|
||||
- Commit-Message enthält Issue-Key (z. B. `MP-7`) → erleichtert Nachverfolgung
|
||||
- In Doku-Front‑Matter `yt_epic`/`yt_issues` pflegen
|
||||
- Optional: GitHub Secrets `YT_URL`, `YT_TOKEN` setzen → CI validiert verlinkte Issues, und `youtrack-sync.yml`
|
||||
kommentiert beim Merge automatisch ins Issue
|
||||
|
||||
## 5) Definition of Done (Auszug)
|
||||
|
||||
- Doku aktuell (README/ADR/C4/API)
|
||||
- Front‑Matter valide (`modul`, `status`, `summary`, optional `last_reviewed`, `review_cycle`, `yt_*`)
|
||||
- Links funktionieren (CI link-check grün)
|
||||
- Tests grün
|
||||
|
||||
## 6) Lokale Tipps
|
||||
|
||||
- Vor dem Push: `markdownlint`, `vale` lokal laufen lassen (optional via pre-commit hooks)
|
||||
- kleine, häufige PRs statt großer Monster-PRs
|
||||
@@ -0,0 +1,66 @@
|
||||
---
|
||||
owner: project-maintainers
|
||||
status: active
|
||||
review_cycle: 365d
|
||||
last_reviewed: 2025-10-28
|
||||
summary: KDoc-Styleguide für die Meldestelle. Mindeststandards für KDoc, damit Dokka lesbare API-Doku generiert.
|
||||
bc: infrastructure
|
||||
doc_type: how-to
|
||||
---
|
||||
|
||||
# KDoc-Styleguide (Kurzfassung)
|
||||
|
||||
Dieser Styleguide definiert die wichtigsten Regeln für KDoc-Kommentare in Kotlin-Projekten der Meldestelle. Ziel:
|
||||
Verständliche, konsistente API-Dokumentation via Dokka (GFM/HTML).
|
||||
|
||||
## Grundregeln
|
||||
|
||||
- Sprache: Deutsch für Fließtexte; Code/Bezeichner bleiben Englisch.
|
||||
- Jeder public class, interface, object, enum, public function und public property erhält einen KDoc-Block.
|
||||
- KDoc beginnt mit einem vollständigen, aussagekräftigen Satz in der dritten Person.
|
||||
- Beispiele und wichtige Hinweise als kurze Absätze oder Listen, keine Romane.
|
||||
|
||||
## Struktur eines KDoc-Blocks
|
||||
|
||||
```kotlin
|
||||
/**
|
||||
* Beschreibt prägnant, was das Element macht und warum es existiert.
|
||||
*
|
||||
* Details: Optionale Erläuterung von Parametern, Nebenwirkungen, Fehlerfällen.
|
||||
*
|
||||
* @param id Eindeutige Kennung des Members
|
||||
* @return Das gefundene Objekt oder null, wenn nicht vorhanden
|
||||
* @throws IllegalArgumentException Falls Parameter ungültig sind
|
||||
*/
|
||||
fun findMember(id: MemberId): Member?
|
||||
```
|
||||
|
||||
## Tags
|
||||
|
||||
- @param: Für jeden Parameter bei public Funktionen
|
||||
- @return: Wenn Rückgabewert semantisch relevant ist
|
||||
- @throws: Relevante Exceptions dokumentieren
|
||||
- @since, @see: Sparsam verwenden, wenn es wirklichen Mehrwert bringt
|
||||
|
||||
## Stil & Sprache
|
||||
|
||||
- Klar, knapp, aktiv. Keine Redundanz.
|
||||
- Domänenbegriffe verwenden (BCs: members, horses, events, masterdata, infrastructure).
|
||||
- Keine Interna oder Secrets dokumentieren.
|
||||
|
||||
## Beispielschnipsel
|
||||
|
||||
```kotlin
|
||||
/** Erstellt einen neuen Event und persistiert ihn transaktional. */
|
||||
fun createEvent(cmd: CreateEventCommand): EventId
|
||||
```
|
||||
|
||||
## Dokka-Hinweise
|
||||
|
||||
- Dokka erzeugt GFM (Markdown) unter build/dokka/gfm und HTML unter build/dokka/html.
|
||||
- Source-Link führt auf GitHub (main-Branch). Prüfe Links in der CI.
|
||||
|
||||
## Review
|
||||
|
||||
- PR-Checklist: "KDoc vollständig?" anhaken, wenn neue public APIs hinzugekommen sind.
|
||||
- Vale/markdownlint gelten nur für .md; KDoc wird redaktionell in Code-Reviews geprüft.
|
||||
@@ -0,0 +1,67 @@
|
||||
# Start Local (Lokales Setup)
|
||||
|
||||
Kurzanleitung, um das Projekt lokal in wenigen Minuten zu starten.
|
||||
|
||||
## Voraussetzungen
|
||||
- Docker und Docker Compose (v2)
|
||||
- Java 25 (JDK)
|
||||
- Git
|
||||
|
||||
## Schnellstart
|
||||
|
||||
```bash
|
||||
# 1) Repository klonen
|
||||
git clone https://github.com/StefanMoCoAt/meldestelle.git
|
||||
cd meldestelle
|
||||
|
||||
# 2) Runtime-Environment vorbereiten (Single Source of Truth)
|
||||
# Kopiere die Vorlage und passe sie bei Bedarf an.
|
||||
cp -n .env.template config/env/.env 2>/dev/null || true
|
||||
# Optionale lokale Geheimnisse/Overrides (gitignored):
|
||||
# echo "POSTGRES_PASSWORD=meinlokalespasswort" >> config/env/.env.local
|
||||
|
||||
# 3) (Optional) Compose-Files generieren
|
||||
# (nur falls du die Generator-Pipeline nutzt)
|
||||
# DOCKER_SSOT_MODE=envless bash scripts/generate-compose-files.sh all development
|
||||
|
||||
# 4) Infrastruktur starten (Postgres, Redis, Kafka, Keycloak, Monitoring, Gateway)
|
||||
docker compose -f docker-compose.yaml up -d
|
||||
|
||||
# 5) Backend-Service starten (Beispiel: Results Service)
|
||||
./gradlew :backend:services:results:results-service:bootRun
|
||||
# oder – falls zentral gewollt und unterstützt:
|
||||
# ./gradlew bootRun
|
||||
```
|
||||
|
||||
Sobald die Infrastruktur läuft, erreichst du unter anderem:
|
||||
- Gateway: http://localhost:8081
|
||||
- Keycloak: http://localhost:8180
|
||||
- Grafana: http://localhost:3000
|
||||
- Prometheus: http://localhost:9090
|
||||
|
||||
## Tests ausführen
|
||||
```bash
|
||||
./gradlew test
|
||||
# Spezifisches Modul
|
||||
./gradlew :backend:services:results:results-service:test
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
- Dienste starten nicht? Ports belegt oder Logs prüfen:
|
||||
```bash
|
||||
docker ps
|
||||
docker logs <container-name>
|
||||
```
|
||||
- Infrastruktur neu starten:
|
||||
```bash
|
||||
docker compose -f docker-compose.yaml down -v
|
||||
docker compose -f docker-compose.yaml up -d
|
||||
```
|
||||
- Environment-Variablen: in `config/env/.env` und optional `config/env/.env.local`.
|
||||
|
||||
## Weiterführende Hinweise
|
||||
- Architektur: `docs/ARCHITECTURE.md`
|
||||
- ADRs: `docs/adr/`
|
||||
- C4-Diagramme: `docs/c4/`
|
||||
|
||||
Stand: Dezember 2025
|
||||
Reference in New Issue
Block a user