Skip to main content
Diese Seite behandelt Entwicklungskonventionen und Code-Qualitätsstandards. Für den vollständigen Beitragsleitfaden – einschließlich des Pioneer Program, Feldtests, PR-Prozess und Community-Links – siehe CONTRIBUTING.md auf GitHub.

​
Einrichtung

Voraussetzungen: Python 3.11+, uv, Node.js 18+, pnpm.
LLM_API_KEY ist nur erforderlich, um das Backend lokal auszuführen oder eine automatisch übersetzte Locale-Ausgabe bei Commit in der Vorschau anzuzeigen. Mitwirkende ohne einen Schlüssel können weiterhin EN-Änderungen committen — ein GitHub Actions-Workflow übersetzt nach dem PR-Merge auf master. Siehe i18n unten.
Überprüfen Sie, dass alles funktioniert:

​
Typsicherheit

mypy strict mode ist erzwungen. Die gesamte Codebasis besteht ohne Fehler, und der Pre-Commit-Hook führt mypy auf jeder gestaffelten .py-Datei mit vollständiger Import-Chain-Überprüfung aus. Regeln:
  • Typ-Hinweise erforderlich auf allen öffentlichen Funktionen.
  • Kein # type: ignore außer für import-untyped (Bibliotheken von Drittanbietern ohne Stubs).
  • Verwenden Sie from __future__ import annotations für Forward References.
  • Beheben Sie die tatsächlichen Typen – unterdrücken Sie niemals Fehler, um CI zu bestehen.

​
Testen

Jedes neue Modul muss eine entsprechende Testdatei haben. Jeder Feature-Commit muss Tests enthalten. Regeln:
  • Alle vorhandenen Tests müssen vor dem Commit erfolgreich sein: uv run pytest tests/ -x -q.
  • Tests dürfen nicht von externen Diensten abhängen — mocken Sie Datenbanken, MCP-Server, HTTP-Endpunkte und LLM-Aufrufe mit unittest.mock / AsyncMock.
  • Führen Sie Tests mit Coverage aus: uv run pytest --cov=fim_one.

​
Code-Stil

  • Async-first. Verwenden Sie async def für I/O-gebundene Operationen. Wrappen Sie synchrone Aufrufe mit asyncio.to_thread() anstatt den Event Loop zu blockieren.
  • Ruff zum Linting. uv run ruff check src/ — Zeilenlänge beträgt 100 Zeichen.
  • Minimale __init__.py Exporte. Exportieren Sie nur die öffentliche API; halten Sie interne Symbole privat.
  • Paketmanager. uv für Python, pnpm für Frontend. Verwenden Sie niemals pip oder npm.

​
Git-Konventionen

Atomare Commits. Eine logische Änderung pro Commit. Teilen Sie unabhängige Änderungen auf, auch wenn sie zusammen entwickelt wurden. Commit-Nachrichtenformat: type: description Hooks niemals überspringen mit --no-verify. Die Pre-Commit-Pipeline existiert, um Fehler zu erkennen, bevor sie das Repository erreichen.

​
Pre-commit Hook-Pipeline

Der Hook wird bei jedem Commit automatisch ausgeführt. Er verarbeitet nur gestaffelte Dateien, die für jeden Schritt relevant sind – wenn Sie nur Python-Dateien geändert haben, wird der i18n-Schritt übersprungen und umgekehrt. Wenn ein Schritt fehlschlägt, wird der Commit abgebrochen. Beheben Sie die gemeldeten Fehler und versuchen Sie es erneut.

​
i18n

FIM One unterstützt 6 Sprachen (EN, ZH, JA, KO, DE, FR). Übersetzungen sind vollständig automatisiert. Bearbeiten Sie nur englische Quelldateien:
  • frontend/messages/en/{namespace}.json — UI-Strings
  • docs/*.mdx (Stammebene, nicht in Locale-Unterverzeichnissen) — Dokumentation
  • README.md — Projekt-Readme
Andere Locale-Dateien (messages/zh/, docs/zh/, README.zh.md usw.) werden automatisch generiert und der Pre-Commit-Hook lehnt Commits ab, die diese manuell bearbeiten. Um eine Fehlübersetzung zu beheben, bearbeiten Sie scripts/translation-glossary.md — die in jeden Übersetzungs-Prompt injizierte Single Source of Truth für jede Übersetzungsregel — und generieren Sie dann betroffene Dateien mit uv run scripts/translate.py --files <en-sources> --force neu. Jede Glossar-Korrektur gilt dauerhaft für alle fünf Sprachen. Zwei Wege zur Generierung von Locale-Dateien:
  1. Lokaler Pre-Commit-Hook — wird ausgeführt, wenn LLM_API_KEY in .env gesetzt ist. Die Übersetzung erfolgt vor dem Push, sodass Sie die Ausgabe in der Vorschau anzeigen können.
  2. CI-Fallback — wenn der lokale Hook keinen Schlüssel hatte und übersprungen wurde, übersetzt .github/workflows/i18n-sync.yml nach dem Merge auf master und committed das Ergebnis automatisch.
Mitwirkende ohne API-Schlüssel können EN-Änderungen frei committen — der CI-Pfad stellt sicher, dass Locales korrekt landen. Neuen i18n-Namespace hinzufügen: Erstellen Sie messages/en/{ns}.json — andere Locale-Dateien werden beim nächsten Commit oder nach dem Merge auf CI generiert. Vollständige Neuübersetzung erzwingen: uv run scripts/translate.py --all (erfordert lokalen LLM_API_KEY).

​
Datenbankmigrationen

Dev verwendet SQLite, Produktion verwendet PostgreSQL. Ein Satz von Alembic-Migrationsdateien muss auf beiden funktionieren. Wichtige Regeln:
  • Jedes neue ORM-Modell oder jede neue Spalte muss eine Migration haben — verlassen Sie sich niemals auf metadata.create_all().
  • Alle Migrationen müssen idempotent sein — verwenden Sie Hilfsfunktionen aus fim_one.migrations.helpers (table_exists, table_has_column, index_exists).
  • Boolean-Standardwerte: server_default=sa.text("FALSE") / sa.text("TRUE"). Niemals "0" / "1" — PostgreSQL lehnt Integer-Literale für Boolean-Spalten ab.
  • SQLite kann ALTER COLUMN nicht ausführen — verwenden Sie op.batch_alter_table() für Änderungen an Spaltenbeschränkungen.
  • Nach dem Schreiben einer Migration führen Sie sofort uv run alembic upgrade head aus, um sie anzuwenden.

​
Kurzreferenz