From 734903788096816ed01a9acec25f348deee6fadb Mon Sep 17 00:00:00 2001 From: Ulas Kalayci Date: Mon, 4 May 2026 20:06:44 +0200 Subject: [PATCH] docs: add repo cleanup design specification Design document for comprehensive repository and documentation maintenance after v0.45.0 release. Covers archiving strategy for implemented plans/specs, BACKLOG/CHANGELOG updates, and README improvements. Co-Authored-By: Claude Sonnet 4.5 --- .../designs/2026-05-04-repo-cleanup-design.md | 218 ++++++++++++++++++ 1 file changed, 218 insertions(+) create mode 100644 docs/designs/2026-05-04-repo-cleanup-design.md diff --git a/docs/designs/2026-05-04-repo-cleanup-design.md b/docs/designs/2026-05-04-repo-cleanup-design.md new file mode 100644 index 0000000..b4e1ead --- /dev/null +++ b/docs/designs/2026-05-04-repo-cleanup-design.md @@ -0,0 +1,218 @@ +# Oikos Repository Cleanup Design + +**Datum:** 2026-05-04 +**Status:** Approved +**Ziel:** Umfassende Pflege des GitHub Repos und der Projektdokumentation nach Release v0.45.0 + +## Überblick + +Nach der erfolgreichen Implementierung von CardDAV Contacts Integration (v0.45.0) und Generic CalDAV Multi-Account Sync (v0.44.0) hat sich eine erhebliche Menge an abgeschlossenen Implementierungsplänen, Design-Specs und Audit-Dokumenten angesammelt. Diese Pflege-Aktion bringt die Projektdokumentation auf den aktuellen Stand, indem implementierte Dokumente archiviert, veraltete Inhalte entfernt und aktuelle Dokumentation aktualisiert werden. + +## Hintergrund + +### Analysierte Zeitspanne +CHANGELOG v0.40.0 bis v0.45.0 (1. Mai - 4. Mai 2026): +- v0.40.0: Budget Loans Tracker, Dashboard Widget Sizes +- v0.41.0: Birthday Badge, Filter Chips, Calendar Improvements +- v0.42.0: Module Toggles, Bulk Actions +- v0.43.0: Automatic Scheduled Backups +- v0.44.0: Generic CalDAV Multi-Account Sync +- v0.44.1: CalDAV Migration Crash Fix +- v0.45.0: CardDAV Contacts Integration, Multi-Value Contact Fields + +### Identifizierte Probleme + +1. **BACKLOG.md veraltet** - "Completed Features" endet bei v0.41.0, BL-11 (CardDAV) noch in "Open Entries" obwohl implementiert +2. **PROGRESS.md obsolet** - Session-spezifisches Tracking-Dokument für v0.45.0 +3. **README.md unvollständig** - Contacts-Beschreibung erwähnt CardDAV Multi-Account Sync nicht +4. **26 Markdown-Dateien in docs/** - viele implementierte Pläne/Specs/Audits +5. **Emojis im CHANGELOG** - inkonsistent mit Projektstil + +## Entscheidungen + +Basierend auf Klärungsfragen wurden folgende Strategien festgelegt: + +1. **Archivierung:** Implementierte Pläne/Specs/Designs → `docs/archive/` (Option B) +2. **PROGRESS.md:** Löschen, da im Git-Verlauf erhalten (Option A) +3. **BACKLOG.md:** Auf "Open Entries" reduzieren, "Completed" streichen (Option C) +4. **Audit-Dateien:** Alle nach `docs/archive/` (Option A) +5. **Design-Dokumente:** Nach `docs/archive/designs/` (Custom) +6. **awesome-selfhosted/:** Behalten (Custom) +7. **superpowers/specs + plans:** Nach `docs/archive/superpowers/` (Option A) +8. **README.md:** Contacts-Beschreibung komplett neu formulieren (Option C) +9. **Emojis:** Aus CHANGELOG entfernen, nirgends neu einbauen +10. **Vorgehen:** Thematische Commits (Ansatz A) + +## Design + +### 1. Archivierungsstrategie + +**Ziel:** Implementierte Pläne, Specs und Design-Dokumente aus dem aktiven Arbeitsbereich entfernen, aber als historische Referenz bewahren. + +**Archivstruktur:** +``` +docs/archive/ +├── designs/ +│ ├── 2026-05-04-cardav-api-routes-implementation.md +│ ├── 2026-05-04-cardav-contacts-design.md +│ └── 2026-05-04-generic-caldav-design.md +├── superpowers/ +│ ├── plans/ +│ │ ├── 2026-04-20-ics-subscription.md +│ │ ├── 2026-04-21-installer-system.md +│ │ ├── 2026-04-25-ux-accessibility-fixes.md +│ │ ├── 2026-04-26-ux-improvements.md +│ │ ├── 2026-04-27-ux-ui-optimization.md +│ │ ├── 2026-04-29-ux-improvements.md +│ │ ├── 2026-04-29-ux-navigation-improvements.md +│ │ ├── 2026-04-29-ux-navigation-redesign.md +│ │ ├── 2026-04-30-microinteraction-long-loops.md +│ │ ├── 2026-05-04-cardav-contacts.md +│ │ └── 2026-05-04-generic-caldav.md +│ └── specs/ +│ ├── 2026-04-20-ics-subscription-design.md +│ ├── 2026-04-27-ux-ui-optimization-design.md +│ ├── 2026-04-29-ux-navigation-redesign-design.md +│ └── ICS_URL_Subscription_v2.md +├── color-redesign-proposal.md +├── installer-plan.md +├── installer-recon.md +├── premium-ui-audit.md +└── ux-audit-plan.md +``` + +**Vorgehen:** +1. Erstelle Archivverzeichnisse: `docs/archive/`, `docs/archive/designs/`, `docs/archive/superpowers/plans/`, `docs/archive/superpowers/specs/` +2. Verschiebe Dateien mit `git mv` (erhält Git-Historie) +3. `docs/awesome-selfhosted/` bleibt unberührt + +**Dateien insgesamt:** 23 Markdown-Dateien + +### 2. Bereinigungsstrategie + +**Ziel:** Session-spezifische Tracking-Dokumente entfernen, deren Information bereits im Git-Verlauf und CHANGELOG konserviert ist. + +**Zu löschende Dateien:** +- `PROGRESS.md` (CardDAV v0.45.0 Session-Tracking) + +**Vorgehen:** +1. `git rm PROGRESS.md` +2. Keine weiteren Löschungen im Root oder docs/ + +**Begründung:** PROGRESS.md war ein temporäres Arbeitsdokument für die CardDAV-Implementierung. Alle relevanten Informationen sind in: +- Git-Commits (detaillierte Implementierungsschritte) +- CHANGELOG.md (User-facing Änderungen) +- Archivierte Design-Docs (technische Spezifikation) + +### 3. Aktualisierungsstrategie + +**Ziel:** BACKLOG.md und CHANGELOG.md auf aktuellen Stand bringen und vereinfachen. + +**BACKLOG.md Änderungen:** +1. BL-11 (CardDAV) aus "Open Entries" entfernen - implementiert in v0.45.0 +2. "Completed Features" Sektion komplett streichen - CHANGELOG.md ist die autoritäre Quelle +3. Struktur vereinfachen zu: + +```markdown +# Backlog + +Feature requests and planned extensions. Entries here will **not** be implemented until explicitly prioritized and moved into a release branch. + +New suggestion? → [Open an issue](https://github.com/ulsklyc/oikos/issues/new?template=feature_request.md) or add it here. + +## Open Entries + +| ID | Issue | Feature | Notes | +|----|-------|---------|-------| +| *Currently no open backlog items* | | | | +``` + +**CHANGELOG.md Änderungen:** +1. Alle Emojis entfernen - durchgehend für alle Versionen +2. Keine inhaltlichen Änderungen - nur Emoji-Bereinigung + +### 4. Verbesserungsstrategie (README.md) + +**Ziel:** Contacts-Modul-Beschreibung aktualisieren, um CardDAV Multi-Account Sync widerzuspiegeln. + +**Aktueller Stand:** +```markdown +| **Notes & Contacts** | Colored sticky notes with Markdown support. Contact directory with vCard import/export. | +``` + +**Neue Formulierung:** +```markdown +| **Notes & Contacts** | Colored sticky notes with Markdown support. Contact directory with multi-account CardDAV sync (Nextcloud, iCloud, Radicale, Baikal), multiple phones/emails/addresses per contact, and vCard import/export. | +``` + +**Änderungen:** +- Ergänzt: "multi-account CardDAV sync" mit Provider-Beispielen (konsistent mit Calendar-Zeile) +- Ergänzt: "multiple phones/emails/addresses per contact" (v0.45.0 Feature) +- Behalten: "vCard import/export" (existierendes Feature) +- Keine Emojis + +**Keine weiteren README-Änderungen** - restliche Modul-Beschreibungen bleiben unberührt. + +### 5. Commit-Strategie + +**Ziel:** Vier thematische Commits mit klaren, aussagekräftigen Nachrichten. + +**Commit 1: Archivierung** +``` +docs: archive implemented plans, specs, and design documents + +Move completed implementation plans (2026-04-20 to 2026-05-04), +design specs, and audit documents to docs/archive/ for historical +reference while keeping the main docs/ directory focused on active +documentation. + +Archived: +- 11 implementation plans (superpowers/plans/) +- 4 design specs (superpowers/specs/) +- 3 design documents (designs/) +- 5 audit/proposal documents (root level) +``` + +**Commit 2: Bereinigung** +``` +docs: remove session-specific PROGRESS.md + +Remove CardDAV v0.45.0 session tracking document. Information is +preserved in git history, CHANGELOG.md, and archived design docs. +``` + +**Commit 3: Aktualisierung** +``` +docs: update BACKLOG and remove emojis from CHANGELOG + +- BACKLOG.md: remove BL-11 (implemented in v0.45.0), strip "Completed + Features" section (CHANGELOG is authoritative source) +- CHANGELOG.md: remove all emojis for consistency +``` + +**Commit 4: Verbesserung** +``` +docs: update README Contacts module description + +Reflect v0.45.0 CardDAV multi-account sync and multi-value contact +fields (multiple phones/emails/addresses per contact). +``` + +## Erfolgskriterien + +1. **Archiv erstellt:** `docs/archive/` mit korrekter Struktur existiert +2. **23 Dateien archiviert:** Alle implementierten Pläne/Specs/Designs verschoben +3. **PROGRESS.md entfernt:** Datei existiert nicht mehr im Root +4. **BACKLOG.md vereinfacht:** Nur "Open Entries", keine "Completed Features", BL-11 entfernt +5. **CHANGELOG.md emoji-frei:** Keine Emojis in allen Versionen +6. **README.md aktualisiert:** Contacts-Beschreibung spiegelt v0.45.0 Features wider +7. **4 Commits erstellt:** Jeder mit klarer, thematischer Nachricht +8. **Git-Historie erhalten:** `git mv` verwendet, keine Commits verloren +9. **Keine Emojis hinzugefügt:** Weder in README noch in anderen Dateien + +## Nicht-Ziele + +- SPEC.md überprüfen oder aktualisieren (separate Aufgabe) +- Weitere README-Sektionen ändern (nur Contacts-Modul) +- docs/installation.md oder andere aktive Docs ändern +- Inhaltliche Änderungen an CHANGELOG.md (nur Emoji-Entfernung)