[Doku] Wiki vollständig machen + Auto-Sync (Ordner→Tab) + Konvention: jede neue Funktion ins Wiki #205

New issue

Open

opened 2026-06-29 21:43:03 +00:00 by chinux · 0 comments

chinux commented

2026-06-29 21:43:03 +00:00

Owner

Ziel

(1) Wiki-Sync automatisieren (Ordner wiki/ → Gitea-Wiki-Tab), (2) vollständiger Feature-Coverage-Check + Nachtrag der Doku, (3) Konvention verankern, damit jede neue Funktion künftig automatisch im Wiki landet.

Hintergrund

Doku wird im wiki/-Ordner des Haupt-Repos gepflegt; der Wiki-Tab ist ein separates Repo (theProx.wiki.git). Beide waren auseinandergelaufen (Ordner aktuell/15+ Seiten, Tab alt/8 Seiten mit kaputten Namen) — inzwischen manuell deckungsgleich gemacht. Es fehlt: ein Automatismus, der das so hält, und eine systematische Coverage, damit kein Feature undokumentiert bleibt.

Quelle der Wahrheit = wiki/-Ordner. Der Tab wird daraus gesynct, nie direkt editiert.

Aufgabe 1 — Sync automatisieren

scripts/sync-wiki.sh: Wiki-Repo (.wiki.git) aktualisieren, wiki/*.md hineinkopieren, im Wiki-Repo nicht mehr existierende Seiten entfernen (Ordner = Wahrheit), committen+pushen. Idempotent, Credentials aus Umgebung (nicht hardcoden).
.gitea/workflows/wiki-sync.yml: triggert auf push nach main bei Änderungen unter wiki/** → ruft das Script. Damit landet jede Doku-Änderung automatisch im Tab.
Saubere Seitennamen (kein URL-Encoding).

Aufgabe 2 — Vollständiger Feature-Coverage-Check + Nachtrag

Ebene = Feature/Capability, NICHT jede Funktionssignatur (47k LOC einzeln zu dokumentieren ist weder machbar noch nützlich).

Coverage-Matrix (z. B. wiki/_Coverage.md): alle Feature-Bereiche vs. vorhandene Wiki-Seiten. Quellen:
- Backend: alle server/routers/*.py (admin, audit, auth, auto_update, backup, command, deploy, docker, faq, log, me, monitor, net, notification, rdp, schedule, security, task, temperature, template, tunnel, update, upgrade).
- Agents: Node-Agent (Commands/Allowlist, Self-Update, Tunnel, VM-Listener), VM-Guest-Agent (Linux/FreeBSD), Windows-Agent.
- Frontend: Node-Tabs (overview/info/vms/backup/network/jobs/updates/ports/security/audit/logs), VM-Modal-Tabs, TaskDock, BulkUpdateMode, Notification-Settings.
- Querschnitt: Auth/RBAC (#185, #181, fail2ban), Transport/VPN-Toggle (#187/#189), Self-Update (#187 TLS+sha256), Auto-Update-Scheduler (#174), Enrollment, Mandanten-Scope (#108), Migrationen.
Lücken füllen: je Bereich ohne Doku neue Seite (saubere Namen) bzw. Abschnitt. Inhalt: Was es tut, wie der User es nutzt (UI-Pfad/Endpoint/Command), Config/ENV, Grenzen. Gegen echten Code verifizieren (Datei:Zeile als Anker), nichts erfinden.
Home.md: alle Seiten verlinken (auch die aktuell verwaisten Agents-Übersicht + Windows-VM-Guest-Agent), thematisch gruppiert, keine toten Links.
Veraltetes korrigieren: z. B. Self-Update-Signing auf TLS/sha256 statt ed25519-Signatur (#187).

Realismus: Wenn zu groß für einen Lauf → Matrix VOLLSTÄNDIG erstellen, Lücken priorisiert füllen (nutzernächste zuerst: Updates/Docker, Tunnel/RDP, Notifications, Backup, Scheduler), offene Bereiche im Abschluss vermerken. Keine Platzhalter-Pfusch-Seiten.

Aufgabe 3 — Konvention verankern

wiki/Development.md → "Konventionen" → neue Regel Dokumentation: "Jede neue nutzerrelevante Funktion (Endpoint, Agent-Command, Frontend-Tab/Panel, Hintergrund-Job, Config/ENV-Flag) MUSS im selben Change im wiki/-Ordner dokumentiert werden. Der Wiki-Tab wird automatisch via scripts/sync-wiki.sh (CI) synchronisiert — nie direkt im Tab editieren, immer im wiki/-Ordner. Ein Change ohne Wiki-Eintrag gilt als unvollständig."

Akzeptanz

sync-wiki.sh + CI-Workflow vorhanden; Ordner-Änderung landet automatisch im Tab.
Coverage-Matrix existiert; jeder Feature-Bereich hat Doku oder ist als offen markiert.
Home.md verlinkt alle Seiten, keine toten/verwaisten Links.
Development.md enthält die Dokumentations-Konvention.
Veraltete Seiten korrigiert; nichts erfunden.

Branch

docs/wiki-coverage-and-autosync

## Ziel (1) Wiki-Sync **automatisieren** (Ordner wiki/ → Gitea-Wiki-Tab), (2) **vollständiger Feature-Coverage-Check** + Nachtrag der Doku, (3) **Konvention** verankern, damit jede neue Funktion künftig automatisch im Wiki landet. ## Hintergrund Doku wird im **wiki/-Ordner** des Haupt-Repos gepflegt; der **Wiki-Tab** ist ein separates Repo (`theProx.wiki.git`). Beide waren auseinandergelaufen (Ordner aktuell/15+ Seiten, Tab alt/8 Seiten mit kaputten Namen) — inzwischen manuell deckungsgleich gemacht. Es fehlt: ein **Automatismus**, der das so hält, und eine **systematische Coverage**, damit kein Feature undokumentiert bleibt. **Quelle der Wahrheit = wiki/-Ordner.** Der Tab wird daraus gesynct, nie direkt editiert. ## Aufgabe 1 — Sync automatisieren - `scripts/sync-wiki.sh`: Wiki-Repo (.wiki.git) aktualisieren, `wiki/*.md` hineinkopieren, im Wiki-Repo nicht mehr existierende Seiten entfernen (Ordner = Wahrheit), committen+pushen. Idempotent, Credentials aus Umgebung (nicht hardcoden). - `.gitea/workflows/wiki-sync.yml`: triggert auf push nach main bei Änderungen unter `wiki/**` → ruft das Script. Damit landet jede Doku-Änderung automatisch im Tab. - Saubere Seitennamen (kein URL-Encoding). ## Aufgabe 2 — Vollständiger Feature-Coverage-Check + Nachtrag Ebene = **Feature/Capability**, NICHT jede Funktionssignatur (47k LOC einzeln zu dokumentieren ist weder machbar noch nützlich). 1. **Coverage-Matrix** (z. B. `wiki/_Coverage.md`): alle Feature-Bereiche vs. vorhandene Wiki-Seiten. Quellen: - Backend: alle `server/routers/*.py` (admin, audit, auth, auto_update, backup, command, deploy, docker, faq, log, me, monitor, net, notification, rdp, schedule, security, task, temperature, template, tunnel, update, upgrade). - Agents: Node-Agent (Commands/Allowlist, Self-Update, Tunnel, VM-Listener), VM-Guest-Agent (Linux/FreeBSD), Windows-Agent. - Frontend: Node-Tabs (overview/info/vms/backup/network/jobs/updates/ports/security/audit/logs), VM-Modal-Tabs, TaskDock, BulkUpdateMode, Notification-Settings. - Querschnitt: Auth/RBAC (#185, #181, fail2ban), Transport/VPN-Toggle (#187/#189), Self-Update (#187 TLS+sha256), Auto-Update-Scheduler (#174), Enrollment, Mandanten-Scope (#108), Migrationen. 2. **Lücken füllen**: je Bereich ohne Doku neue Seite (saubere Namen) bzw. Abschnitt. Inhalt: Was es tut, wie der User es nutzt (UI-Pfad/Endpoint/Command), Config/ENV, Grenzen. **Gegen echten Code verifizieren** (Datei:Zeile als Anker), nichts erfinden. 3. **Home.md**: alle Seiten verlinken (auch die aktuell verwaisten Agents-Übersicht + Windows-VM-Guest-Agent), thematisch gruppiert, keine toten Links. 4. **Veraltetes korrigieren**: z. B. Self-Update-Signing auf TLS/sha256 statt ed25519-Signatur (#187). Realismus: Wenn zu groß für einen Lauf → Matrix VOLLSTÄNDIG erstellen, Lücken priorisiert füllen (nutzernächste zuerst: Updates/Docker, Tunnel/RDP, Notifications, Backup, Scheduler), offene Bereiche im Abschluss vermerken. Keine Platzhalter-Pfusch-Seiten. ## Aufgabe 3 — Konvention verankern - `wiki/Development.md` → "Konventionen" → neue Regel **Dokumentation**: "Jede neue nutzerrelevante Funktion (Endpoint, Agent-Command, Frontend-Tab/Panel, Hintergrund-Job, Config/ENV-Flag) MUSS im selben Change im wiki/-Ordner dokumentiert werden. Der Wiki-Tab wird automatisch via scripts/sync-wiki.sh (CI) synchronisiert — nie direkt im Tab editieren, immer im wiki/-Ordner. Ein Change ohne Wiki-Eintrag gilt als unvollständig." ## Akzeptanz - sync-wiki.sh + CI-Workflow vorhanden; Ordner-Änderung landet automatisch im Tab. - Coverage-Matrix existiert; jeder Feature-Bereich hat Doku oder ist als offen markiert. - Home.md verlinkt alle Seiten, keine toten/verwaisten Links. - Development.md enthält die Dokumentations-Konvention. - Veraltete Seiten korrigiert; nichts erfunden. ## Branch `docs/wiki-coverage-and-autosync`

chinux added the

tech-debt

label

2026-06-29 21:43:03 +00:00