# 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](https://github.com/accelaire/CLAIR/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](https://github.com/accelaire/CLAIR/discussions).

---

## 🛠️ 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](/guide/guide-developpeur/demarrage-local).
3. Avant d'ouvrir la pull request vers `master`, lancer :

```bash
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`.

4. **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](/donnees/qualite-des-donnees)) :

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

5. **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](/donnees/modele-prisma#migrations)). Une nouvelle table reçoit aussi son trigger `updated_at`.

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

7. **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](/changelog).

---

## ✍️ Conventions

### Commits

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

```text
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](/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.
