From 94e8057d732515d41acadc9c768e0a45b78cefc1 Mon Sep 17 00:00:00 2001 From: fds2610-bot Date: Wed, 19 Aug 2026 20:28:10 +0200 Subject: [PATCH] =?UTF-8?q?Fix=20#43:=20CONTRIBUTE.md=20und=20Setup-Skript?= =?UTF-8?q?=20f=C3=BCr=20Mitwirkende?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CONTRIBUTE.md beschreibt Wege für Beiträge, gesuchte Unterstützung und die drei bindenden Leitlinien (FOSS, Datensparsamkeit, Security) mit einem Disclaimer, dass VIBE Coding ausdrücklich erlaubt ist. dev-setup.sh im Repo-Root richtet Docker, Fork/Upstream-Checkout, lokale Container und optional die E2E-Testinfrastruktur ein. Co-Authored-By: Claude Sonnet 5 --- CONTRIBUTE.md | 166 ++++++++++++++++++++++++++++++++++++++++++++++++++ Changes.md | 14 +++++ README.md | 1 + dev-setup.sh | 123 +++++++++++++++++++++++++++++++++++++ 4 files changed, 304 insertions(+) create mode 100644 CONTRIBUTE.md create mode 100755 dev-setup.sh diff --git a/CONTRIBUTE.md b/CONTRIBUTE.md new file mode 100644 index 0000000..5dd61cc --- /dev/null +++ b/CONTRIBUTE.md @@ -0,0 +1,166 @@ +# Mitmachen + +## Disclaimer: VIBE Coding ist ausdrücklich erlaubt + +Dieses Projekt ist mit intensivem Einsatz von LLMs entstanden – Architektur, +Implementierung, Tests und Dokumentation liefen zu einem großen Teil über +Claude Code. Das ist kein Betriebsunfall, sondern bewusste Arbeitsweise. Wer +hier mitmachen möchte, muss also keine Glaubensfrage klären: Ob eine Änderung +per Hand geschrieben oder mit einem Coding-Agenten erarbeitet wurde, spielt für +die Aufnahme keine Rolle. Wichtig ist, was am Ende im PR steht – nachvollziehbar, +getestet, den Leitlinien unten folgend. + +## Leitlinien + +Diese drei Punkte sind die grundsätzliche Haltung des Autors und für dieses +Projekt bindend. Mitwirkende dürfen fachlich anderer Meinung sein – an diesen +Leitplanken selbst ändert das nichts. + +1. **FOSS – Open Source first.** Der Code enthält keine proprietären + Bestandteile. So, wie er in diesem Repository liegt, ist er vollständig + nutzbar – ohne versteckte Abhängigkeit von einem externen Dienst, einer + kostenpflichtigen Lizenz oder einer geschlossenen Komponente. +2. **Datensparsamkeit.** Wer die Anwendung betreibt, hat jederzeit maximale + Transparenz darüber, welche Daten verarbeitet werden. Es gibt keine + Telemetrie und keine Übermittlung von Nutzdaten an die Autoren dieses + Repos. Werden Daten irgendwohin verschickt, die der Nutzer nicht selbst + konfiguriert hat, gilt das als Security-Bug mit höchster Priorität. +3. **Security.** Das Modul soll jederzeit dem Stand der Technik entsprechen. + Gemeldete Sicherheitslücken werden mit oberster Priorität behoben. Da es + sich dabei um vertrauliche Informationen handelt: **bitte nicht als + öffentliches Issue melden**, sondern direkt per E-Mail an + [fds2610@sonnengetrock.net](mailto:fds2610@sonnengetrock.net). + +## Wie mithelfen? + +Damit ein Beitrag wirklich ankommt, bitte einen der folgenden Wege nutzen: + +1. Ein Issue auf [Codeberg](https://codeberg.org/fds2610/Finanzmanager/issues) + anlegen – als **BUG** oder **FEATURE**. +2. Einen Pull Request aus einem eigenen Fork erstellen. +3. Eine E-Mail an [fds2610@sonnengetrock.net](mailto:fds2610@sonnengetrock.net). + +Besonders willkommen ist Unterstützung bei: + +- **Dokumentation** (kann immer verbessert werden) +- **Übersetzungen** +- **Bugfixes** +- **Feature-Umsetzungen** + +Aktuell review ich jeden Pull Request persönlich. Das ist bei wachsendem +Interesse möglicherweise irgendwann ein Flaschenhals – dann werde ich mir +etwas überlegen. Bis dahin: etwas Geduld beim Review einplanen. + +Fachbegriffe im Code und in der Oberfläche folgen bewusst dem Original +(Lexware FinanzManager) und bleiben deutsch – siehe die Begriffsliste in +[`CLAUDE.md`](CLAUDE.md). Neue Wortschöpfungen oder englische Entsprechungen +bitte vermeiden. + +## Entwicklungsumgebung aufsetzen + +Das Setup ist bewusst schlank gehalten: Auf dem Host werden nur **Docker**, +**Git** und optional **Claude Code** benötigt – alles Projektspezifische läuft +in Containern. Kein lokales PHP, kein Composer, kein MariaDB auf dem Host. + +Wer alle Schritte auf einmal ausführen will, nutzt das Setup-Skript: + +```bash +./dev-setup.sh +``` + +Es fragt nichts nach, was sich per Flag oder Umgebungsvariable vorgeben lässt +(siehe `./dev-setup.sh --help`), und lässt sich beliebig oft erneut ausführen. +Im Folgenden die einzelnen Schritte, die das Skript automatisiert. + +### 0. Voraussetzungen auf dem Host + +Nur was zwingend nötig ist, um überhaupt Container starten und Code verwalten +zu können: + +- **Docker** (inkl. Compose-Plugin) +- **Git** +- optional **Claude Code**, wenn mit einem Coding-Agenten gearbeitet werden + soll + +Alles andere – PHP, Composer, MariaDB, Node/Playwright für die E2E-Tests – +bleibt in Containern gekapselt. + +### 1. Fork, Remotes und Zugangsdaten + +Dieses Repository arbeitet mit zwei Remotes: dem persönlichen Fork (`origin`, +wohin gepusht wird) und dem Upstream-Repository (`upstream`, von dem gezogen +wird): + +```bash +git clone https://codeberg.org//Finanzmanager.git +cd Finanzmanager +git remote add upstream https://codeberg.org/fds2610/Finanzmanager.git +git fetch upstream +``` + +Für Pull Requests reicht ein persönliches [Zugriffs-Token](https://codeberg.org/user/settings/applications) +mit Schreibrechten auf den eigenen Fork. Wer die Entwicklung automatisiert +(z. B. über einen eigenen Bot-Account, wie es dieses Repo mit dem +`fds2610-bot`-Account und dem Token in `CODEBERG_BOT_TOKEN` tut), legt dafür +einen separaten Account an, forkt darüber das Upstream-Repo und authentifiziert +sich mit dem Bot-Token statt dem persönlichen: + +```bash +curl -s -X POST "https://codeberg.org/api/v1/repos/fds2610/Finanzmanager/forks" \ + -H "Authorization: token $CODEBERG_BOT_TOKEN" + +git remote set-url origin "https://:${CODEBERG_BOT_TOKEN}@codeberg.org//Finanzmanager.git" +``` + +Der eigentliche Beitrag – Issue, PR, E-Mail – läuft aber unabhängig davon, +ob mit persönlichem Token oder Bot-Setup gearbeitet wird. + +### 2. Lokale Container starten + +```bash +cp .env.example .env +docker compose up -d +``` + +Die Anwendung ist danach unter **http://localhost:8000** erreichbar +(Port aus `docker-compose.yml`). Migrationen spielt der Container beim Start +automatisch ein, siehe `docker-entrypoint.sh`. Die Test-Suite: + +```bash +./scripts/run-tests.sh +``` + +### 3. E2E-Tests (optional) + +Browser-Tests laufen über ein separates, generisches Playwright-Runner-Projekt +(`e2e-runner`), das **nicht** Teil dieses Repos ist und standardmäßig unter +`~/projects/e2e-runner` erwartet wird. Ist es nicht vorhanden, überspringt +`tests/e2e/run.sh` die E2E-Tests automatisch mit einer Warnung – nichts +schlägt deswegen fehl. Wer es einrichten möchte: + +```bash +docker compose exec -u www-data php php scripts/e2e-benutzer.php # Testnutzer anlegen +tests/e2e/run.sh # läuft, sobald der Runner existiert +``` + +Details und abweichende Pfade/URLs stehen in `tests/e2e/README.md`. + +### 4. Claude Code auf dem Projektverzeichnis + +Claude Code wird im ausgecheckten Projektverzeichnis gestartet und liest +[`CLAUDE.md`](CLAUDE.md) als verbindliche Betriebs- und Coding-Regeln – unter +anderem: keine lokale Installation von PHP/Composer/MariaDB ohne Rückfrage, +Tests immer im Container als `www-data`, SQL nur über `Database::…` mit +Prepared Statements, deutsche Fachbegriffe. Darüber hinausgehende, riskante +Aktionen (Force-Push, Löschen, Schema-Änderungen außerhalb von `migrations/` +usw.) bestätigt Claude Code vor der Ausführung interaktiv – das entspricht dem +Standard-Berechtigungsmodell von Claude Code und wurde für dieses Projekt +nicht erweitert. Wer Claude Code stärker automatisiert einsetzen möchte (z. B. +für wiederkehrende Aufgaben ohne Rückfrage), regelt das über die eigene +`.claude/settings.json` – das ist eine persönliche Entscheidung und nicht Teil +dieses Repos. + +## Lizenz + +MIT, siehe [`LICENSE`](LICENSE). Beiträge werden unter derselben Lizenz +angenommen. diff --git a/Changes.md b/Changes.md index 4559e2e..b0da1a6 100644 --- a/Changes.md +++ b/Changes.md @@ -1,5 +1,19 @@ # Änderungen +## CONTRIBUTE.md und Setup-Skript für Mitwirkende (19.08.2026) + +`CONTRIBUTE.md` beschreibt, wie Beiträge ankommen (Issue, PR, E-Mail), welche +Unterstützung gesucht wird und die drei bindenden Leitlinien des Projekts: FOSS, +Datensparsamkeit und Security mit direktem Kontakt an fds2610@sonnengetrock.net +für Sicherheitslücken. Vorangestellt ist ein Disclaimer, dass VIBE Coding +ausdrücklich erlaubt ist – das Projekt selbst ist mit intensivem LLM-Einsatz +entstanden (Feature #43). + +Neu ist außerdem `dev-setup.sh` im Repo-Root: richtet Docker (optional), +Checkout mit Fork- und Upstream-Remote, lokale Container und optional die +E2E-Testinfrastruktur ein. Zielverzeichnis, E2E-Setup und Docker-Installation +lassen sich über Flags oder Umgebungsvariablen abweichend vom Default setzen. + ## Kontoblatt: Typeahead für die Kategorie (19.08.2026) Die Kategorie ließ sich im Kontoblatt nur über eine lange Auswahlliste finden – bei vielen diff --git a/README.md b/README.md index 6642db9..e4bcab5 100644 --- a/README.md +++ b/README.md @@ -130,6 +130,7 @@ wieder ein. Einzelheiten in `docs/import-export.md`. - `PLAN.md` – Projektplan mit allen Phasen - `CLAUDE.md` – Entwicklungsregeln +- `CONTRIBUTE.md` – Mitmachen: Leitlinien, Wege für Beiträge, Entwicklungsumgebung - `Changes.md` – Änderungsprotokoll - `docs/stammdaten.md` – Konten, Kontengruppen, Kategorien, Klassen - `docs/buchungen.md` – Kontoblatt, Umbuchungen, Splitbuchungen, Salden diff --git a/dev-setup.sh b/dev-setup.sh new file mode 100755 index 0000000..817b844 --- /dev/null +++ b/dev-setup.sh @@ -0,0 +1,123 @@ +#!/usr/bin/env bash +# +# Richtet eine lokale Entwicklungsumgebung für den Finanzmanager ein: +# Docker (optional), Zielverzeichnis mit den Git-Remotes (origin = eigener +# Fork, upstream = fds2610/Finanzmanager), lokale Container und optional die +# Infrastruktur für die E2E-Tests. Auf dem Host wird sonst nichts installiert +# – PHP, Composer und MariaDB laufen ausschließlich in Containern. +# +# Beliebig oft erneut ausführbar. +# +# ./dev-setup.sh [Optionen] +# +# Optionen (mit Default, alles auch als Umgebungsvariable setzbar): +# --verzeichnis PFAD Zielverzeichnis für den Checkout +# (WORKDIR, Default: ~/projects/Finanzmanager) +# --fork ACCOUNT Codeberg-Account des eigenen Forks (FORK_ACCOUNT) +# --kein-e2e E2E-Testsetup nicht mit einrichten (E2E_SETUP=nein) +# --keine-docker-installation +# Docker nicht installieren, auch wenn es fehlt +# (DOCKER_INSTALL=nein) +# -h, --help Diese Hilfe anzeigen +# +# Beispiel: +# ./dev-setup.sh --verzeichnis ~/code/Finanzmanager --fork meinaccount + +set -euo pipefail + +WORKDIR="${WORKDIR:-$HOME/projects/Finanzmanager}" +FORK_ACCOUNT="${FORK_ACCOUNT:-}" +E2E_SETUP="${E2E_SETUP:-ja}" +DOCKER_INSTALL="${DOCKER_INSTALL:-ja}" +UPSTREAM_URL="https://codeberg.org/fds2610/Finanzmanager.git" + +melde() { printf '\n\033[1m▸ %s\033[0m\n' "$1"; } + +hilfe() { + sed -n '2,25p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//' +} + +while [ $# -gt 0 ]; do + case "$1" in + --verzeichnis) WORKDIR="$2"; shift 2 ;; + --fork) FORK_ACCOUNT="$2"; shift 2 ;; + --kein-e2e) E2E_SETUP=nein; shift ;; + --keine-docker-installation) DOCKER_INSTALL=nein; shift ;; + -h|--help) hilfe; exit 0 ;; + *) echo "Unbekannte Option: $1" >&2; hilfe; exit 1 ;; + esac +done + +# ── 0. Docker und Git ──────────────────────────────────────────────────────── +melde "Voraussetzungen prüfen" + +if ! command -v git >/dev/null 2>&1; then + echo "Git fehlt und muss manuell installiert werden (siehe Distribution)." >&2 + exit 1 +fi + +if ! docker compose version >/dev/null 2>&1; then + if [ "$DOCKER_INSTALL" = "ja" ]; then + echo "Docker/Compose-Plugin fehlt – Installation über get.docker.com." + curl -fsSL https://get.docker.com | sh + echo "Ggf. den aktuellen Benutzer zur Gruppe 'docker' hinzufügen und neu anmelden:" + echo " sudo usermod -aG docker \$USER" + else + echo "Docker/Compose-Plugin fehlt und --keine-docker-installation ist gesetzt." >&2 + exit 1 + fi +else + echo "Docker vorhanden: $(docker compose version --short 2>/dev/null || echo ok)" +fi + +# ── 1. Checkout mit Fork- und Upstream-Remote ─────────────────────────────── +melde "Repository unter $WORKDIR" + +if [ -d "$WORKDIR/.git" ]; then + echo "Vorhanden – kein erneuter Checkout." +else + if [ -z "$FORK_ACCOUNT" ]; then + echo "Kein --fork angegeben: Checkout direkt aus dem Upstream-Repository." + echo "Für einen eigenen Beitrag vorher auf Codeberg forken und mit" + echo "'--fork ' erneut ausführen." + git clone "$UPSTREAM_URL" "$WORKDIR" + else + git clone "https://codeberg.org/$FORK_ACCOUNT/Finanzmanager.git" "$WORKDIR" + fi +fi + +cd "$WORKDIR" +git remote get-url upstream >/dev/null 2>&1 || git remote add upstream "$UPSTREAM_URL" +git fetch upstream --quiet || true + +# ── 2. Lokale Container ───────────────────────────────────────────────────── +melde "Container starten" + +[ -f .env ] || cp .env.example .env +docker compose up -d + +melde "Migrationen" +docker compose exec -T php php scripts/migrate.php + +echo "Anwendung erreichbar unter http://localhost:8000" + +# ── 3. E2E-Testsetup (optional) ───────────────────────────────────────────── +if [ "$E2E_SETUP" = "ja" ]; then + melde "E2E-Testnutzer" + docker compose exec -u www-data -T php php scripts/e2e-benutzer.php || true + echo "E2E-Tests laufen über ein separates Runner-Projekt unter" + echo "~/projects/e2e-runner (nicht Teil dieses Repos). Fehlt es, überspringt" + echo "tests/e2e/run.sh die Tests automatisch mit einer Warnung." + echo "Details: tests/e2e/README.md" +else + echo "E2E-Setup übersprungen (--kein-e2e)." +fi + +# ── 4. Claude Code ─────────────────────────────────────────────────────────── +melde "Claude Code" +echo "Im Verzeichnis '$WORKDIR' starten, z.B. mit: claude" +echo "Die Betriebs- und Coding-Regeln stehen in CLAUDE.md und werden automatisch" +echo "gelesen. Für weitergehende Automatisierung ohne Rückfragen die eigene" +echo ".claude/settings.json anpassen (persönliche Entscheidung, nicht Teil des Repos)." + +melde "Fertig"