docs: agent instructions (language, checks, release order via CI, UI rules)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
sandrodachandClaude Opus 5.5 committed
1 parent
599d53e0ea
commit
f5281a5aea
2 files changed
+82
No files matched your search
@@ -0,0 +1,81 @@
|
||||
# Hinweise für Coding-Agenten
|
||||
|
||||
Regeln für die Arbeit an MindSift, die nicht aus dem Code selbst hervorgehen. Aufbau und Technik stehen in [Doku/](Doku/README.md), vor allem [architecture.md](Doku/architecture.md).
|
||||
|
||||
## Sprache und Stil
|
||||
|
||||
- **Deutsch:** Oberflächentexte, Fehlermeldungen für Nutzer, E-Mails, `CHANGELOG.md`, `README.md`, `Doku/`.
|
||||
- **Englisch:** Code-Kommentare und Commit-Nachrichten.
|
||||
- **Commit-Nachrichten** im Stil `feat(bereich): …`, `fix(bereich): …`, `docs: …`, `style(bereich): …`. Am Ende die Zeile `Co-Authored-By: …` des jeweiligen Agenten.
|
||||
- Neuer Code richtet sich nach dem umgebenden Code: Benennung, Kommentardichte, vorhandene Helfer statt neuer Varianten.
|
||||
|
||||
## Umgebung
|
||||
|
||||
Auf dem Entwicklungsrechner sind weder Node noch Go installiert. Alles läuft in Containern (podman):
|
||||
|
||||
```bash
|
||||
# Frontend: Typen, Lint, Tests
|
||||
podman run --rm -v "$PWD/frontend":/app:Z -w /app docker.io/library/node:22-alpine \
|
||||
sh -c "npx tsc --noEmit && npx eslint src/… && npx vitest run"
|
||||
|
||||
# Backend: vet und Tests
|
||||
podman run --rm -v "$PWD":/src:Z -w /src docker.io/library/golang:1.24-alpine \
|
||||
sh -c "go vet ./... && go test ./internal/..."
|
||||
```
|
||||
|
||||
Die Linter-Warnungen `react-hooks/exhaustive-deps` gibt es schon länger; neuer Code soll keine zusätzlichen Warnungen bringen.
|
||||
|
||||
## Prüfen während der Arbeit
|
||||
|
||||
- **Gezielt prüfen:** `tsc`, die betroffenen Frontend-Tests, `go vet` und `go test`. Den vollen Build macht nur der Server (siehe Release-Ablauf); ein kompletter `podman build .` vorher ist doppelte Arbeit.
|
||||
- **Oberfläche im Browser ansehen**, besonders Handy-Ansichten: Image bauen, im Demo-Modus starten, mit Playwright aus dem `e2e/`-Ordner prüfen (Vorbild: `e2e/screenshots.sh`). Handy-Emulation mit `isMobile: true, hasTouch: true`; Finger-Gesten lassen sich über das Chrome DevTools Protocol (`Input.dispatchTouchEvent`) nachstellen.
|
||||
|
||||
```bash
|
||||
podman build -q -t mindsift-check .
|
||||
podman run -d --rm --name ms-check --network host -e PORT=18555 -e MINDA_DEMO=true \
|
||||
-e DEMO_RESET_MINUTES=0 -e JWT_SECRET=check-only mindsift-check
|
||||
# Demo-Anmeldung: admin/admin bzw. user/user
|
||||
```
|
||||
- **Zeitabhängiger Code** (Alarme, Tageszusammenfassung, Begrüßungen, Termine): nie `time.Now()` dort, wo eine übergebene Zeit gemeint ist. Die betroffenen Go-Tests zusätzlich mit verschiedenen `TZ`-Werten laufen lassen (z. B. `Europe/Berlin`, `America/Los_Angeles`, `Asia/Tokyo`). Ein uhrzeitabhängiger Test hat schon einmal einen Release verhindert, weil er nur vormittags grün war.
|
||||
|
||||
## Release-Ablauf
|
||||
|
||||
**Committen** ist jederzeit erlaubt. **Jeder Push ist ein Release**, also mit Version und CHANGELOG-Eintrag.
|
||||
|
||||
1. **Version erhöhen** (SemVer: Fehlerbehebung → Patch, neue Funktion → Minor):
|
||||
- `frontend/package.json` (Feld `version`)
|
||||
- `frontend/package-lock.json`: nur die beiden Versionszeilen von MindSift selbst (Zeile 3 und 9), nicht die gleichlautenden Versionen von Abhängigkeiten
|
||||
- Versions-Badge oben in `README.md`
|
||||
2. **CHANGELOG:** neuer Abschnitt `## [x.y.z] - JJJJ-MM-TT` unter `## [Unreleased]` (Format *Keep a Changelog*, Abschnitte Added/Changed/Fixed), unten die Vergleichslinks `[Unreleased]` und `[x.y.z]` anpassen. Einträge auf Deutsch und aus Sicht der Nutzer.
|
||||
3. **Doku nachziehen**, wenn sich Verhalten oder API ändern (`README.md`, `Doku/api/rest.md`, `Doku/architecture.md`).
|
||||
4. Committen, dann **nur nach `dev` pushen**.
|
||||
5. **Warten, bis der `dev`-Build auf dem Server grün ist.** Schlägt er fehl: auf `dev` beheben, nicht nach `main` mergen.
|
||||
6. Nach `main` mergen (`git merge --no-ff dev -m "Merge dev into main (vx.y.z)"`) und pushen.
|
||||
7. **Warten, bis der `main`-Build grün ist.** Erst dann gilt das Release als draußen.
|
||||
|
||||
Ist ein Release nie gebaut worden (CI fehlgeschlagen), bleibt die Versionsnummer, und die Korrektur kommt in denselben CHANGELOG-Abschnitt.
|
||||
|
||||
**Git-Tags nur auf ausdrücklichen Wunsch.** Tags lassen zusätzliche Images bauen; genutzt werden nur `:dev` und `:latest`. Wenn gewünscht: `git tag -a vx.y.z -m "MindSift vx.y.z"` auf den Merge-Commit in `main` und den Tag pushen.
|
||||
|
||||
Fremde Branches (z. B. von anderen Agenten) werden vor dem Mergen geprüft.
|
||||
|
||||
### CI auf dem Git-Server
|
||||
|
||||
- Workflow: `.gitea/workflows/build-and-publish.yaml`, Entscheidung in `.gitea/scripts/build-plan.sh`.
|
||||
- `dev` → Image `:dev`, mit allen Tests (Dockerfile: tsc, Lint, Frontend-Tests, `go vet`, Go-Tests).
|
||||
- `main` → Image `:latest` mit `APP_VERSION=v<package.json-Version>`; überspringt die Tests, wenn `:dev` aus demselben Code gebaut wurde. Deshalb erst nach grünem `dev`-Build mergen.
|
||||
- Tag `v*` → `:vx.y.z` und `:stable`.
|
||||
- Status der letzten Läufe:
|
||||
|
||||
```bash
|
||||
curl -s "https://git.dsit.me/api/v1/repos/sandrodach/MindSift/actions/tasks?limit=4"
|
||||
# workflow_runs[].head_branch / .status (success|failure|…) / .display_title
|
||||
```
|
||||
|
||||
## Oberfläche
|
||||
|
||||
- **Einheitliche Bedienelemente:** Personen-Suche, Profilbild-Stapel, Zähler und weitere Muster stehen in [Doku/ui-patterns.md](Doku/ui-patterns.md). Vorhandene Komponenten verwenden statt neuer Varianten; neue gemeinsame Muster dort ergänzen.
|
||||
- **Handy und Desktop:** Unter `sm` ist Handy-Layout, ab `lg` die volle Desktop-Ansicht (z. B. Seitenleiste neben der Notiz). Wird nur das Handy geändert, bleiben die Werte ab `sm`/`lg` exakt wie vorher.
|
||||
- **Antippen am Handy:** Ziele mindestens 44 px hoch (`h-11 sm:h-…`). Auf reinen Touch-Geräten gibt es kein HTML5-Drag-&-Drop; Kanban nutzt dafür `useKanbanTouchDrag`, die Notizen die Leiste über der Tastatur (`MobileOutlineBar`).
|
||||
- **Themes:** Farben nur über die Theme-Variablen bzw. Klassen (`bg-panel`, `bg-canvas`, `text-main`, `text-muted`, `border-border`, `bg-accent` …), keine festen Farben. Rahmen mit `bg-panel`/`bg-canvas` bekommen die Ecken des Themes automatisch; liegt darin ein Kopfbereich mit eigenem Hintergrund, braucht der Rahmen `overflow-hidden`, sonst ragen bei runden Ecken die Kanten heraus.
|
||||
- **Installierte App (PWA):** Manifest-Änderungen (Farben, Verknüpfungen) übernimmt Android erst, wenn es die App aktualisiert (bis etwa einen Tag) oder nach Neuinstallation; normaler App-Code kommt beim nächsten Start. Ändert sich der Cache-Inhalt des Service Workers, `VERSION` in `frontend/public/sw.js` erhöhen.
|
||||
Reference in new issue
Block a user