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
- Vérifier que le bug n'a pas déjà été signalé dans les issues.
- 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
- Forker le dépôt, puis créer une branche depuis
master:feat/…,fix/…,docs/…. - Installer l'environnement : voir Démarrage local.
- Avant d'ouvrir la pull request vers
master, lancer :
Code
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.
- 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) :
Code
-
Si le schéma Prisma change, joindre à la PR le fichier de migration, écrit à partir d'un
prisma migrate diffrelu :pnpm db:migratene fonctionne pas sur ce dépôt (voir Modèle Prisma). Une nouvelle table reçoit aussi son triggerupdated_at. -
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. -
Si le changement est notable (site, API, données, méthodologie, outillage), ajouter un fragment
.changelog/<sujet>.mdqui alimentera la prochaine version ; sinon, écrire la ligneJournal : aucundans 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
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,e2eet 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 :
camelCasepour les variables et fonctions,PascalCasepour les types,kebab-casepour les fichiers. - API : un module par domaine dans
apps/api/src/modules/<domaine>/(.controller.ts,.service.ts,.schema.tsen 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.