Finanzmanager/CONTRIBUTE.md

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.

Wie mithelfen?

Damit ein Beitrag wirklich ankommt, bitte einen der folgenden Wege nutzen:

1. Ein Issue auf Codeberg anlegen – als BUG oder FEATURE.
2. Einen Pull Request aus einem eigenen Fork erstellen.
3. Eine E-Mail an 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. 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:

./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):

git clone https://codeberg.org/<dein-fork-account>/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 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:

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://<bot-account>:${CODEBERG_BOT_TOKEN}@codeberg.org/<bot-account>/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

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:

./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:

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 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. Beiträge werden unter derselben Lizenz angenommen.