> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fim.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Beitragen

> Entwicklungskonventionen, Typsicherheit, Tests und Code-Qualitätsstandards für FIM One-Mitwirkende.

<Tip>
  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](https://github.com/fim-ai/fim-one/blob/master/CONTRIBUTING.md).
</Tip>

## Einrichtung

Voraussetzungen: Python 3.11+, [uv](https://docs.astral.sh/uv/), Node.js 18+, pnpm.

```bash theme={null}
git clone https://github.com/fim-ai/fim-one.git && cd fim-one
cp example.env .env                        # LLM_API_KEY is optional for contributors
uv sync --all-extras                       # Python dependencies
cd frontend && pnpm install && cd ..       # frontend dependencies
bash scripts/setup-hooks.sh                # pre-commit hooks (required)
```

<Note>
  `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](#i18n) unten.
</Note>

Überprüfen Sie, dass alles funktioniert:

```bash theme={null}
uv run pytest tests/ -x -q                # tests
uv run mypy src/fim_one/                   # type check
uv run ruff check src/                     # lint
cd frontend && pnpm build && cd ..         # frontend build
```

***

## 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.

| Konvention | Muster                       |
| ---------- | ---------------------------- |
| Datei      | `tests/test_{module}.py`     |
| Klasse     | `Test{Feature}`              |
| Methode    | `test_{behavior_under_test}` |

**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`

| Type       | Wann zu verwenden                             |
| ---------- | --------------------------------------------- |
| `feat`     | Neue benutzergerichtete Funktion              |
| `fix`      | Fehlerbehebung                                |
| `refactor` | Code-Umstrukturierung ohne Verhaltensänderung |
| `docs`     | Nur Dokumentation                             |
| `test`     | Tests hinzufügen oder aktualisieren           |
| `chore`    | Build, CI, Abhängigkeitsaktualisierungen      |

**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.

| Reihenfolge | Schritt                   | Auslöser                                                                                                                                       | Funktion                                                                                                        |
| ----------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| 0           | Locale-Edit-Schutz        | Alle gestaffelten Dateien unter `messages/{locale}/`, `docs/{locale}/` oder `README.{locale}.md`                                               | Bricht den Commit ab – kein Override möglich. Beheben Sie Übersetzungen über `scripts/translation-glossary.md`. |
| 1           | OpenAPI-Spec-Regeneration | `src/fim_one/web/**/*.py` geändert                                                                                                             | Exportiert `docs/openapi.json` neu aus FastAPI-Routen                                                           |
| 2           | i18n-Übersetzung          | `messages/en/*.json`, `docs/*.mdx` oder `README.md` geändert (benötigt lokalen `LLM_API_KEY`, sonst wird es nach dem Merge von CI verarbeitet) | Übersetzt neue/geänderte Schlüssel in alle Zielsprachen                                                         |
| 3           | mypy-Typprüfung           | Beliebige `src/fim_one/**/*.py` geändert                                                                                                       | Führt mypy mit vollständiger Import-Kette auf gestaffelten Dateien aus                                          |
| 4           | MDX-Validierung           | Beliebige `.mdx`-Datei gestaffelt                                                                                                              | Validiert JSX/MDX-Syntax, bevor sie Mintlify erreicht                                                           |

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`](https://github.com/fim-ai/fim-one/blob/master/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`](https://github.com/fim-ai/fim-one/blob/master/.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

```bash theme={null}
# Development
./start.sh dev                            # hot reload (Python + Next.js HMR)
./start.sh dev:api                        # API only, dev mode (hot reload)
./start.sh dev:ui                         # Frontend only, dev mode (HMR)
./start.sh api                            # FastAPI only (headless)

# Quality checks
uv run pytest tests/ -x -q               # tests (stop on first failure)
uv run pytest --cov=fim_one              # tests with coverage
uv run mypy src/fim_one/                  # type check
uv run ruff check src/                    # lint

# i18n
uv run scripts/translate.py --all         # force full retranslation

# Database
uv run alembic upgrade head               # apply migrations
uv run alembic revision -m "description"  # create new migration
```