Skip to main content
Cette page couvre les conventions de développement et les normes de qualité du code. Pour le guide complet de contribution — incluant le Programme Pioneer, les tests sur le terrain, le processus de PR et les liens communautaires — consultez CONTRIBUTING.md sur GitHub.

​
Configuration

Prérequis : Python 3.11+, uv, Node.js 18+, pnpm.
LLM_API_KEY est requis uniquement pour exécuter le backend localement ou pour prévisualiser la sortie des paramètres régionaux traduits automatiquement lors de la validation. Les contributeurs sans clé peuvent toujours valider les modifications EN — un workflow GitHub Actions traduit sur master après la fusion de la PR. Voir i18n ci-dessous.
Vérifiez que tout fonctionne :

​
Sécurité des types

Le mode strict de mypy est appliqué. L’ensemble du code passe avec zéro erreur, et le hook pre-commit exécute mypy sur chaque fichier .py staged avec vérification complète de la chaîne d’importation. Règles :
  • Les annotations de type sont requises sur toutes les fonctions publiques.
  • Pas de # type: ignore sauf pour import-untyped (bibliothèques tierces sans stubs).
  • Utilisez from __future__ import annotations pour les références anticipées.
  • Corrigez les types réels — ne supprimez jamais les erreurs pour faire passer la CI.

​
Tests

Chaque nouveau module doit avoir un fichier de test correspondant. Chaque commit de fonctionnalité doit inclure des tests. Règles :
  • Tous les tests existants doivent réussir avant de valider : uv run pytest tests/ -x -q.
  • Les tests ne doivent pas dépendre de services externes — simulez les bases de données, les serveurs MCP, les points de terminaison HTTP et les appels LLM en utilisant unittest.mock / AsyncMock.
  • Exécutez les tests avec couverture : uv run pytest --cov=fim_one.

​
Style de code

  • Async en priorité. Utilisez async def pour les opérations liées aux E/S. Enrobez les appels synchrones avec asyncio.to_thread() plutôt que de bloquer la boucle d’événements.
  • Ruff pour le linting. uv run ruff check src/ — la longueur des lignes est de 100 caractères.
  • Exports __init__.py minimaux. Réexportez uniquement l’API publique ; gardez les symboles internes privés.
  • Gestionnaires de paquets. uv pour Python, pnpm pour le frontend. N’utilisez jamais pip ou npm.

​
Conventions Git

Commits atomiques. Un seul changement logique par commit. Divisez les changements non liés même s’ils ont été développés ensemble. Format du message de commit : type: description Ne jamais contourner les hooks avec --no-verify. Le pipeline de pré-commit existe pour détecter les erreurs avant qu’elles n’atteignent le référentiel.

​
Pipeline de hook de pré-commit

Le hook s’exécute automatiquement à chaque commit. Il traite uniquement les fichiers staged pertinents pour chaque étape — si vous avez modifié uniquement des fichiers Python, l’étape i18n est ignorée, et vice versa. Si une étape échoue, le commit est interrompu. Corrigez les erreurs signalées et réessayez.

​
i18n

FIM One prend en charge 6 langues (EN, ZH, JA, KO, DE, FR). Les traductions sont entièrement automatisées. Modifiez uniquement les fichiers sources en anglais :
  • frontend/messages/en/{namespace}.json — chaînes d’interface utilisateur
  • docs/*.mdx (niveau racine, pas les sous-répertoires de langue) — documentation
  • README.md — readme du projet
Les autres fichiers de langue (messages/zh/, docs/zh/, README.zh.md, etc.) sont générés automatiquement et le hook de pré-commit refuse inconditionnellement les commits qui les modifient manuellement. Pour corriger une mauvaise traduction, modifiez scripts/translation-glossary.md — la source unique de vérité injectée dans le prompt pour chaque règle de traduction — puis régénérez les fichiers affectés avec uv run scripts/translate.py --files <en-sources> --force. Chaque correction du glossaire s’applique à toutes les cinq langues de manière permanente. Deux chemins pour générer les fichiers de langue :
  1. Hook de pré-commit local — s’exécute si LLM_API_KEY est défini dans .env. La traduction se fait avant le push, vous pouvez donc prévisualiser le résultat.
  2. Secours CI — si le hook local n’avait pas de clé et a été ignoré, .github/workflows/i18n-sync.yml traduit sur master après fusion et valide automatiquement le résultat.
Les contributeurs sans clé API peuvent valider librement les modifications EN — le chemin CI garantit que les langues arrivent correctement. Ajouter un nouvel espace de noms i18n : Créez messages/en/{ns}.json — les autres fichiers de langue sont générés lors du prochain commit ou sur CI après fusion. Forcer une retraduction complète : uv run scripts/translate.py --all (nécessite une LLM_API_KEY locale).

​
Migrations de base de données

Dev utilise SQLite, la production utilise PostgreSQL. Un ensemble de fichiers de migration Alembic doit fonctionner sur les deux. Règles clés :
  • Chaque nouveau modèle ORM ou colonne doit avoir une migration — ne jamais compter sur metadata.create_all().
  • Toutes les migrations doivent être idempotentes — utiliser les helpers de fim_one.migrations.helpers (table_exists, table_has_column, index_exists).
  • Valeurs par défaut booléennes : server_default=sa.text("FALSE") / sa.text("TRUE"). Jamais "0" / "1" — PostgreSQL rejette les littéraux entiers pour les colonnes booléennes.
  • SQLite ne peut pas faire ALTER COLUMN — utiliser op.batch_alter_table() pour les modifications de contraintes de colonne.
  • Après avoir écrit une migration, exécuter immédiatement uv run alembic upgrade head pour l’appliquer.

​
Référence rapide