Guide Développeur

Guide de Contribution & Bonnes Pratiques

🤝 Principes

CLAIR est un outil citoyen et apartisan. Les contributions restent factuelles et objectives : aucune opinion politique ne doit transparaître dans le code, les données ou la documentation.


🐞 Signaler un bug

  1. Vérifier que le bug n'a pas déjà été signalé dans les issues.
  2. Ouvrir une issue avec un titre clair, les étapes pour reproduire, le comportement attendu et observé, et l'environnement (OS, Node.js, navigateur).

💡 Proposer une fonctionnalité

Ouvrir une issue qui décrit la fonctionnalité et son utilité, et attendre une validation avant de commencer le développement. La feuille de route est discutée publiquement dans les discussions GitHub.


🛠️ Soumettre du code

  1. Forker le dépôt, puis créer une branche depuis master : feat/…, fix/…, docs/….
  2. Installer l'environnement : voir Démarrage local.
  3. Avant d'ouvrir la pull request vers master, lancer :
TerminalCode
pnpm check # Biome : nouveau front et outillage pnpm lint # ESLint : apps/web, apps/api, ingestion, scripts pnpm --filter <workspace touché> type-check # ex. @clair/api, @clair/ui, @clair/site pnpm test # Vitest, tous les workspaces qui ont des tests # Si un composant de packages/ui est touché pnpm --filter @clair/storybook test:stories # Si une page de apps/site ou un écran de packages/screens est touché pnpm --filter @clair/site build && pnpm test:e2e --project=site # Si la documentation est touchée pnpm docs:nav && pnpm docs:validate

Le pnpm type-check racine passe aussi par apps/web et l'ingestion, qui ont des erreurs préexistantes : on vérifie le workspace touché. En CI, le job front fait le type-check de packages/*, de apps/storybook et de apps/site.

  1. Si l'ingestion, un rattachement ou l'enrichissement IA est touché, lancer aussi les contrôles de la donnée, sur une base remplie (voir Qualité des données) :
TerminalCode
pnpm --filter @clair/ingestion test pnpm --filter @clair/ingestion check-quality pnpm --filter @clair/ingestion exec tsx src/cli.ts check-ia-quality # si l'IA est touchée
  1. Si le schéma Prisma change, joindre à la PR le fichier de migration, écrit à partir d'un prisma migrate diff relu : pnpm db:migrate ne fonctionne pas sur ce dépôt (voir Modèle Prisma). Une nouvelle table reçoit aussi son trigger updated_at.

  2. Si une route de l'API change, modifier son schéma dans apps/api : la référence de l'API de cette documentation est générée depuis lui, jamais écrite à la main.

  3. Si le changement est notable (site, API, données, méthodologie, outillage), ajouter un fragment .changelog/<sujet>.md qui alimentera la prochaine version ; sinon, écrire la ligne Journal : aucun dans la description de la pull request. Format et règles : Journal des versions.


✍️ Conventions

Commits

Messages clairs, en français, au format Conventional Commits, vérifié à chaque commit par commitlint (hook lefthook installé par pnpm install) :

Code
type(portée): description courte corps facultatif, qui explique le pourquoi

Types acceptés (@commitlint/config-conventional) : feat (fonctionnalité), fix (correction), docs (documentation), style (formatage), refactor, perf, test, build, ci, chore (maintenance, dépendances, configuration), revert. La portée est libre (site, ui, api, ingestion, docs, repo, un domaine comme senatoriales…), le sujet peut être long et ne finit pas par un point.

Code

  • TypeScript strict, sans any.
  • Biome (pnpm check, pnpm fix) pour le nouveau front (packages/*, apps/site, apps/storybook), scripts/changelog, e2e et la configuration racine ; le hook de commit formate les fichiers indexés.
  • ESLint (pnpm lint) et Prettier (pnpm format) pour l'existant (apps/web, apps/api, services/ingestion, docs, scripts/*.ts), jusqu'à son passage à Biome.
  • Nouveau front : standards et emplacements dans la section Front et dans AGENTS.md.
  • Nommage : camelCase pour les variables et fonctions, PascalCase pour les types, kebab-case pour les fichiers.
  • API : un module par domaine dans apps/api/src/modules/<domaine>/ (.controller.ts, .service.ts, .schema.ts en Zod, tests à côté).
  • Ingestion : un client par source dans services/ingestion/src/sources/, des tests pour chaque parser, et le respect des limites de débit des sources.

Documentation

Une page par fichier .mdx dans docs/. Après l'ajout, le renommage ou la suppression d'une page, lancer pnpm docs:nav ; les préfixes numériques des dossiers (01-guide) ordonnent la navigation mais n'apparaissent pas dans les URLs. Les diagrammes de la base se régénèrent avec pnpm docs:erd.


⚖️ Licence AGPL-3.0

Toute contribution est placée sous la licence GNU Affero General Public License v3.0, celle du projet.