94e8057d73
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 <noreply@anthropic.com>
166 lines
6.9 KiB
Markdown
166 lines
6.9 KiB
Markdown
# 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/<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](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://<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
|
||
|
||
```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.
|