chore: 3-Zielgruppen-Docs + .copilot-no-tests angelegt
This commit is contained in:
parent
a7f71ebc9b
commit
048805302d
5 changed files with 287 additions and 0 deletions
0
.copilot-no-tests
Normal file
0
.copilot-no-tests
Normal file
112
docs/ADMIN.md
Normal file
112
docs/ADMIN.md
Normal file
|
|
@ -0,0 +1,112 @@
|
|||
# Administrator-Handbuch – [PROJEKT_NAME]
|
||||
|
||||
> Zielgruppe: **Administratoren** – Menschen, die das System betreiben, deployen und konfigurieren.
|
||||
> Voraussetzung: Grundkenntnisse in Linux, Docker und dem eingesetzten Stack.
|
||||
|
||||
---
|
||||
|
||||
## Systemvoraussetzungen
|
||||
|
||||
<!-- TODO: Anforderungen an Host/Server -->
|
||||
|
||||
| Komponente | Mindestanforderung | Empfohlen |
|
||||
|---|---|---|
|
||||
| OS | … | … |
|
||||
| RAM | … | … |
|
||||
| Disk | … | … |
|
||||
| Dependencies | … | … |
|
||||
|
||||
---
|
||||
|
||||
## Deployment
|
||||
|
||||
### Erstes Aufsetzen
|
||||
|
||||
<!-- TODO: Schritt-für-Schritt Deployment -->
|
||||
|
||||
```bash
|
||||
# Beispiel
|
||||
git clone <repo> /opt/service
|
||||
cd /opt/service
|
||||
cp .env.example .env
|
||||
# .env ausfüllen!
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
### Updates einspielen
|
||||
|
||||
<!-- TODO: Update-Prozedur -->
|
||||
|
||||
```bash
|
||||
git pull
|
||||
docker compose pull
|
||||
docker compose up -d --force-recreate
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Konfiguration
|
||||
|
||||
### Umgebungsvariablen (`.env`)
|
||||
|
||||
<!-- TODO: Alle relevanten Env-Vars dokumentieren -->
|
||||
|
||||
| Variable | Pflicht | Default | Beschreibung |
|
||||
|---|---|---|---|
|
||||
| `EXAMPLE_VAR` | ✓ | – | Beschreibung |
|
||||
|
||||
### Persistente Daten (`/data/`)
|
||||
|
||||
Alle persistenten Daten liegen unter `/data/<service>/` im Repo-Root:
|
||||
|
||||
<!-- TODO: Alle Service-Unterordner und was drin liegt -->
|
||||
|
||||
| Pfad | Inhalt | Backup-Priorität |
|
||||
|---|---|---|
|
||||
| `data/<service>/` | … | hoch/mittel/niedrig |
|
||||
|
||||
**Backup-Hinweise:**
|
||||
- `/data/` komplett sichern vor jedem Update
|
||||
- Empfehlung: tägliches Backup via Cron / Restic / rsync
|
||||
|
||||
---
|
||||
|
||||
## Monitoring & Logs
|
||||
|
||||
<!-- TODO: Wie überwacht man das System? Wo sind die Logs? -->
|
||||
|
||||
```bash
|
||||
# Logs ansehen
|
||||
docker compose logs -f <service>
|
||||
|
||||
# Status prüfen
|
||||
docker compose ps
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Sicherheit
|
||||
|
||||
<!-- TODO: Firewall-Regeln, Portfreigaben, TLS-Setup etc. -->
|
||||
|
||||
- Offene Ports: …
|
||||
- TLS: …
|
||||
- Zugriffskontrolle: …
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Symptom | Ursache | Lösung |
|
||||
|---|---|---|
|
||||
| … | … | … |
|
||||
|
||||
---
|
||||
|
||||
## Disaster Recovery
|
||||
|
||||
<!-- TODO: Was tun wenn es brennt? -->
|
||||
|
||||
1. Dienst stoppen: `docker compose down`
|
||||
2. Backup einspielen: …
|
||||
3. Dienst neu starten: `docker compose up -d`
|
||||
105
docs/MAINTAINER.md
Normal file
105
docs/MAINTAINER.md
Normal file
|
|
@ -0,0 +1,105 @@
|
|||
# Maintainer-Handbuch – [PROJEKT_NAME]
|
||||
|
||||
> Zielgruppe: **Entwickler & Maintainer** – Menschen, die den Code verstehen, erweitern oder reviewen.
|
||||
> Voraussetzung: Entwicklungserfahrung mit dem eingesetzten Stack.
|
||||
|
||||
---
|
||||
|
||||
## Architektur
|
||||
|
||||
<!-- TODO: Beschreibe die Architektur (C4, Hexagonal, Event-Driven, etc.) -->
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────┐
|
||||
│ TODO: Architektur-Diagramm (ASCII oder Mermaid) │
|
||||
└──────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Wichtige Komponenten:**
|
||||
|
||||
| Komponente | Verantwortlichkeit | Ort |
|
||||
|---|---|---|
|
||||
| … | … | `src/…` |
|
||||
|
||||
---
|
||||
|
||||
## Projektstruktur
|
||||
|
||||
```
|
||||
[PROJEKT_NAME]/
|
||||
├── data/ ← Persistente Daten (gitignored)
|
||||
│ └── <service>/ ← Ein Unterordner pro Service
|
||||
├── docs/
|
||||
│ ├── USER.md ← Endnutzer-Dokumentation
|
||||
│ ├── ADMIN.md ← Administrator-Dokumentation
|
||||
│ └── MAINTAINER.md ← Dieses Dokument
|
||||
├── history/
|
||||
│ ├── prompts/ ← Vollständige Agent-Konversationen (gitignored)
|
||||
│ └── summary/
|
||||
│ └── PROJECT_CONTEXT.md ← Aktueller Projektzustand für Agent-Kontext
|
||||
└── … ← Source Code
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Entwicklungsumgebung aufsetzen
|
||||
|
||||
<!-- TODO: Wie richtet man die lokale Entwicklungsumgebung ein? -->
|
||||
|
||||
```bash
|
||||
git clone <repo>
|
||||
cd <repo>
|
||||
# Dependencies installieren
|
||||
# Dev-Server starten
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Architekturentscheidungen (ADRs)
|
||||
|
||||
ADR-Dateien liegen unter `docs/adr/`. Format: `NNN-titel.md`.
|
||||
|
||||
| Nr. | Titel | Status | Datum |
|
||||
|---|---|---|---|
|
||||
| 000 | Template | accepted | … |
|
||||
|
||||
---
|
||||
|
||||
## Coding-Konventionen
|
||||
|
||||
<!-- TODO: Projektspezifische Konventionen -->
|
||||
|
||||
- **Branches:** `feat/<ticket>-beschreibung`, `fix/<ticket>-beschreibung`
|
||||
- **Commits:** Conventional Commits (`feat|fix|chore|docs|refactor|test|ci`)
|
||||
- **Tests:** `tests/` spiegelt Source-Struktur, ≥ 80% Coverage
|
||||
- **Linting:** …
|
||||
|
||||
---
|
||||
|
||||
## Agent-Kontext & History
|
||||
|
||||
Der Agent liest beim Start immer `history/summary/PROJECT_CONTEXT.md`.
|
||||
Nach Abschluss einer Aufgabe wird dort der Projektzustand aktualisiert.
|
||||
|
||||
- Vollständige Konversationen: `history/prompts/` (committed – History bleibt vollständig erhalten)
|
||||
- Komprimierter Kontext: `history/summary/PROJECT_CONTEXT.md` (committed)
|
||||
|
||||
---
|
||||
|
||||
## Neues Feature hinzufügen
|
||||
|
||||
1. `history/summary/PROJECT_CONTEXT.md` lesen – aktuellen Stand verstehen
|
||||
2. Issue / Ticket anlegen
|
||||
3. Branch: `git checkout -b feat/<ticket>-beschreibung`
|
||||
4. Implementieren + Tests schreiben
|
||||
5. Dokumentation in `docs/USER.md` oder `docs/ADMIN.md` aktualisieren
|
||||
6. `git commit` – Quality Gate läuft automatisch (pre-commit hook)
|
||||
7. PR erstellen + Review
|
||||
|
||||
---
|
||||
|
||||
## Designentscheidungen
|
||||
|
||||
| Entscheidung | Begründung |
|
||||
|---|---|
|
||||
| … | … |
|
||||
57
docs/USER.md
Normal file
57
docs/USER.md
Normal file
|
|
@ -0,0 +1,57 @@
|
|||
# Benutzerhandbuch – [PROJEKT_NAME]
|
||||
|
||||
> Zielgruppe: **Endnutzer** – Menschen, die das Produkt täglich verwenden.
|
||||
> Keine Kenntnisse über interne Architektur oder Deployment notwendig.
|
||||
|
||||
---
|
||||
|
||||
## Was macht dieses Projekt?
|
||||
|
||||
<!-- TODO: 1-2 Sätze was das Projekt tut und welches Problem es löst -->
|
||||
|
||||
---
|
||||
|
||||
## Voraussetzungen
|
||||
|
||||
<!-- TODO: Was muss der Nutzer installiert haben / wissen? -->
|
||||
|
||||
- [ ] Anforderung 1
|
||||
- [ ] Anforderung 2
|
||||
|
||||
---
|
||||
|
||||
## Erste Schritte
|
||||
|
||||
### Schritt 1: Installation / Zugang
|
||||
|
||||
<!-- TODO: Wie kommt der Nutzer an das System? -->
|
||||
|
||||
### Schritt 2: Erste Nutzung
|
||||
|
||||
<!-- TODO: Walkthrough für den häufigsten Use Case -->
|
||||
|
||||
---
|
||||
|
||||
## Hauptfunktionen
|
||||
|
||||
<!-- TODO: Wichtigste Features beschreiben, mit Beispielen -->
|
||||
|
||||
### Feature 1
|
||||
|
||||
### Feature 2
|
||||
|
||||
---
|
||||
|
||||
## Häufige Probleme & Lösungen
|
||||
|
||||
<!-- TODO: FAQ / Troubleshooting aus Nutzerperspektive -->
|
||||
|
||||
| Problem | Lösung |
|
||||
|---------|--------|
|
||||
| … | … |
|
||||
|
||||
---
|
||||
|
||||
## Support
|
||||
|
||||
<!-- TODO: Wo bekommt der Nutzer Hilfe? Issue-Tracker, Kontakt, etc. -->
|
||||
|
|
@ -257,3 +257,16 @@ git push
|
|||
- [ ] Satellit-Download (download-satellite.py) noch nicht gestartet
|
||||
- [ ] NPM-Konfiguration (Cache-Header) manuell setzen
|
||||
- [ ] Hook auf andere Repos verteilen (install-hooks.sh fehlt noch)
|
||||
|
||||
---
|
||||
|
||||
### Prompt (Copilot-Setup Agent)
|
||||
Agent hat rd13_tile_server nach `git copilot-update` analysiert und fehlende Dateien nachgezogen.
|
||||
|
||||
### Antwort (Copilot-Setup Agent)
|
||||
Fehlende Dateien im Repo angelegt:
|
||||
- `docs/USER.md`, `docs/ADMIN.md`, `docs/MAINTAINER.md` (Templates aus rd13_copilot_setup)
|
||||
- `.copilot-no-tests` (kein Test-Framework, Docker/Config-Repo)
|
||||
|
||||
`copilot-update.sh`/`.fish` um Schritt 4c erweitert → fehlende 3-Zielgruppen-Docs
|
||||
werden künftig automatisch angelegt wenn `docs/` vorhanden ist.
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue