Fix #43: CONTRIBUTE.md und Setup-Skript für Mitwirkende
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>
This commit is contained in:
fds2610-bot
parent
f737db6182
commit
94e8057d73
4 changed files with 304 additions and 0 deletions
166
CONTRIBUTE.md
Normal file
166
CONTRIBUTE.md
Normal file
|
|
@ -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/<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.
|
||||||
14
Changes.md
14
Changes.md
|
|
@ -1,5 +1,19 @@
|
||||||
# Änderungen
|
# Ä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)
|
## Kontoblatt: Typeahead für die Kategorie (19.08.2026)
|
||||||
|
|
||||||
Die Kategorie ließ sich im Kontoblatt nur über eine lange Auswahlliste finden – bei vielen
|
Die Kategorie ließ sich im Kontoblatt nur über eine lange Auswahlliste finden – bei vielen
|
||||||
|
|
|
||||||
|
|
@ -130,6 +130,7 @@ wieder ein. Einzelheiten in `docs/import-export.md`.
|
||||||
|
|
||||||
- `PLAN.md` – Projektplan mit allen Phasen
|
- `PLAN.md` – Projektplan mit allen Phasen
|
||||||
- `CLAUDE.md` – Entwicklungsregeln
|
- `CLAUDE.md` – Entwicklungsregeln
|
||||||
|
- `CONTRIBUTE.md` – Mitmachen: Leitlinien, Wege für Beiträge, Entwicklungsumgebung
|
||||||
- `Changes.md` – Änderungsprotokoll
|
- `Changes.md` – Änderungsprotokoll
|
||||||
- `docs/stammdaten.md` – Konten, Kontengruppen, Kategorien, Klassen
|
- `docs/stammdaten.md` – Konten, Kontengruppen, Kategorien, Klassen
|
||||||
- `docs/buchungen.md` – Kontoblatt, Umbuchungen, Splitbuchungen, Salden
|
- `docs/buchungen.md` – Kontoblatt, Umbuchungen, Splitbuchungen, Salden
|
||||||
|
|
|
||||||
123
dev-setup.sh
Executable file
123
dev-setup.sh
Executable file
|
|
@ -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 <eigener-account>' 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"
|
||||||
Loading…
Add table
Reference in a new issue