commit dbf40c30d885c4175f51f8acdf9673dc8dc7dda5 Author: Stefan Strobl Date: Wed Dec 24 09:50:00 2025 +0100 docs: add literate programming guidelines and project notes Add comprehensive documentation for literate programming approach: - Phase 1 guidelines focusing on why/what without implementation - General literate programming principles for code documentation - Project notes explaining wrapper script concept and strategy Decision: Follow literate programming to make the wrapper maintainable and educational. Comments tell the story, code implements it. This foundation enables better collaboration and knowledge transfer. The notes.md establishes the core concept: a reproducible wrapper around the Void installer that automates error-prone LUKS encryption setup while keeping user control over system configuration choices. diff --git a/.agents/git-commits-rules.md b/.agents/git-commits-rules.md new file mode 100644 index 0000000..433774a --- /dev/null +++ b/.agents/git-commits-rules.md @@ -0,0 +1,41 @@ +# Git-Commit-Regeln + +## Muss + +- Keine KI-/Assistant-Attribution in Commit-Messages (z.B. `Co-authored-by: ChatGPT`). +- Vor dem Commit: verfügbare Checks passend zur Änderung ausführen (Tests/Lint/Format). + +## Umfang + +- 1 logische Änderung pro Commit; klein & atomar. +- Zugehöriges zusammen committen (Code + Tests + Docs derselben Änderung). + +## Message (Conventional Commits) + +``` +(): + + + + + +``` + +- Subject: Imperativ, kein Punkt, ideal `<= 50` Zeichen. +- Body: **was** und **warum**; Kontext nur wenn relevant. + +### Types + +`feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore` + +## Vermeiden + +- Nachrichten wie `fix`, `update`, `refactoring`. +- Unrelated changes in einem Commit. +- Lange Subjects; "was" ohne "warum". + +## Ablauf + +1. In atomare Commits splitten (z.B. `git add -p`). +2. Checks laufen lassen. +3. Commit mit aussagekräftiger Message. diff --git a/.agents/literate-programming.md b/.agents/literate-programming.md new file mode 100644 index 0000000..63bd105 --- /dev/null +++ b/.agents/literate-programming.md @@ -0,0 +1,101 @@ +# Literate Programming + +Hier ist eine **kurze, prägnante und sprachagnostische Anleitung** zu *Literate Programming* **ausschließlich mit Kommentaren in klassischen Quellcode-Dateien**, sodass **kein Build- oder Extraktionsschritt** nötig ist. + +## Ziel + +Der Code bleibt **direkt ausführbar**, während die **Kommentare die primäre Erzählung** bilden. Menschen lesen die Geschichte, Maschinen ignorieren sie. + +## Grundprinzipien + +### 1. Kommentare sind das Hauptmedium + +* Erkläre **Warum**, **Was** und **Wie** im Kommentar. +* Code ist die **konkrete Umsetzung**, nicht der Text. + +```text +# This module computes X. +# The algorithm follows from Y to avoid Z. +``` + +### 2. Erzählerische Struktur statt technischer Reihenfolge + +* Gliedere Kommentare logisch: + + * Motivation + * Konzepte + * Entscheidungen + * Einschränkungen +* Code folgt der Erzählung, nicht umgekehrt. + +```text +# Step 1: Prepare input data +code... + +# Step 2: Core logic +code... +``` + +### 3. Kleine, erklärbare Codeblöcke + +* Jeder Block beantwortet: + **„Was tut dieser Abschnitt – und warum?“** +* Maximal wenige Zeilen Code pro Erklärungseinheit. + +```text +# Filter invalid entries to avoid later edge cases. +code... +``` + +### 4. Kommentare beschreiben Absichten, nicht Syntax + +❌ Schlecht: + +```text +# increment i by 1 +``` + +✅ Gut: + +```text +# Iterate sequentially because order is semantically relevant. +``` + +### 5. Entscheidungen explizit machen + +* Halte Alternativen und Gründe fest. +* Besonders wichtig bei „ungewöhnlichem“ Code. + +```text +# Use an iterative approach instead of recursion +# because maximum depth is unknown at runtime. +``` + +### 6. Stabiler Kommentar-Stil + +* Einheitliche Marker (z. B. `#`, `//`, `/* */`) +* Optional: leichte Strukturierung + +```text +# === Motivation === +# === Algorithm === +# === Edge cases === +``` + +### 7. Leserorientiert schreiben + +* Schreibe für einen **zukünftigen Menschen**, nicht für dich selbst. +* Setze kein implizites Kontextwissen voraus. + +## Faustregel + +> **Wenn man die Kommentare entfernt, sollte der Code schwer verständlich sein. +> Wenn man den Code entfernt, sollte die Idee klar bleiben.** + +## Vorteile dieses Ansatzes + +* ✔ Kein Build- oder Extraktionsschritt +* ✔ Funktioniert in jeder Sprache +* ✔ Versionskontroll-freundlich +* ✔ Direkt im Editor lesbar +* ✔ Wartung und Wissenstransfer verbessert diff --git a/.agents/lp-phase-1.md b/.agents/lp-phase-1.md new file mode 100644 index 0000000..4c5000e --- /dev/null +++ b/.agents/lp-phase-1.md @@ -0,0 +1,37 @@ +# Phase 1 beim Literate Programming + +- In dieser Phase wird **kein Sourcecode** geschrieben; es entstehen nur narrative Kommentartexte. +- Schreibe den literalen Anteil dessen, was umgesetzt werden soll: **Warum** und **Was** (Motivation, Konzepte, Entscheidungen, Einschränkungen), **nicht** das **Wie**. +- Halte Entscheidungen und Alternativen explizit fest, aber **ohne** Implementierungsdetails oder API-/Algorithmus-Spezifika. +- Stelle Rückfragen, wenn Dinge unklar sind oder mehrere sinnvolle Optionen bestehen; diese Phase ist ein Dialog zur Klärung. +- Strukturiere die Texte in klaren, kleinen Abschnitten, die später als Kommentarblöcke vor Codeblöcken stehen können. +- Verteile die Texte über mehrere Dateien entsprechend der späteren Modulstruktur; jede Datei erzählt einen zusammenhängenden Abschnitt. +- Zielkriterium: Wenn man den Code entfernt, bleibt die Idee vollständig verständlich. + +## Vorlage Phase 1 Textblock + +- Passe das Kommentar-Praefix an die Zielsprache an (z. B. `#`, `//`, `/* */`). +- Schreibe die Inhalte in technischem Englisch; vermeide Implementierungsdetails. + +```text +# === Motivation === +# +# === Problem Statement === +# +# === Scope === +# In scope: <...> +# Out of scope: <...> +# === Concepts === +# +# === Decisions === +# because +# === Alternatives Considered === +#