CLAIR DocsCLAIR Docs
  • clair.vote
  • GitHub
  • Nous soutenir
Nous soutenir
  • Accueil
  • Plateforme & Guide
  • Données & Base de Données
  • Journal des versions
  • Explorateur API
CLAIR

Plateforme citoyenne de transparence politique. Données 100% publiques, 0% d'opinion.

Explorer

  • Députés
  • Sénateurs
  • Groupes politiques
  • Sujets
  • Dossiers législatifs
  • Scrutins
  • Agenda
  • Lobbying

Ressources

  • Nous soutenir
  • À propos
  • Méthodologie
  • Contact
  • Comprendre
  • Guide pratique
  • API ouverte

Légal

  • Mentions légales
  • Confidentialité
  • CGU

© 2026 CLAIR. Sources : Assemblée nationale · Sénat · HATVP · Ministère de l'Intérieur · DILA

Vue d'ensembleVersion v0.5.0Version v0.4.0Version v0.3.0Version v0.2.0Version v0.1.0
Journal des versions

Journal des versions

CLAIR avance par versions : des paliers numérotés vX.Y.Z qui regroupent plusieurs semaines ou mois de travail. Chaque version a sa page dans ce menu, de la plus récente à la plus ancienne : un résumé, les faits marquants expliqués (schémas, exemples d'appels à l'API), puis les notes complètes. Pour v0.1.0 à v0.5.0, ces notes reprennent telles quelles celles des tags annotés publiés par le mainteneur.

Le site et l'API sont déployés en continu : une version ne correspond pas à un déploiement, c'est un palier qui dit ce qui a changé et si c'est compatible. Le déploiement en cours est identifié par son commit, et sa version est annoncée par GET /health (champ version) et par la spécification OpenAPI (info.version).

TerminalCode
curl https://api.clair.vote/health # { "status": "ok", "version": "0.5.0", "commit": "…", … }

🗓️ Les versions en un coup d'œil

Les versions de CLAIR
VersionPubliée leThèmesVolume
v0.5.002/10/2026Sénatoriales 2026, législatures précédentes, débats rattachés aux votes, pages de séance272 commits, 13 PR
v0.4.012/06/2026Commissions, agenda parlementaire, sujets enrichis, archives de votes55 commits, 7 PR
v0.3.019/04/2026Enrichissement IA, sujets, classements, fiches parlementaires93 commits, 10 PR
v0.2.025/02/2026Dossiers législatifs, liaison des votes, filtres90 commits, 8 PR
v0.1.007/01/2026Première version publique—

🔢 Ce que signifie le numéro

CLAIR suit le versionnage sémantique, avec une seule version pour tout le dépôt (site, API, ingestion, documentation).

NiveauQuandExemple
Majeur Xrupture pour les réutilisateurs : route ou champ de l'API retiré ou changé de sens, nouvelle version de l'API (/api/v2)suppression d'une route de /api/v1
Mineur Ypalier thématique : nouvelles pages, nouvelles sources, nouveaux champs d'API (ajouts compatibles), nouvelle méthodologiev0.5.0, Sénatoriales 2026
Correctif Zcorrections et améliorations sans nouveauté notable, entre deux palierscorrection d'un calcul

Tant que la version commence par 0., l'API n'est pas déclarée stable : une rupture peut arriver dans une version mineure, et elle est alors annoncée explicitement dans sa page. Le passage en 1.0.0 marquera l'engagement de stabilité de /api/v1.


🧩 Deux niveaux : fragments et versions

FragmentVersion
Quoiune note courte sur un changementun palier qui regroupe les fragments en attente
Quanddans chaque pull request notablequand le mainteneur décide de publier un palier
Où.changelog/<sujet>.md, à la racine du dépôtune page ici (docs/03-changelog/vX-Y-Z.mdx), un tag annoté vX.Y.Z et une GitHub Release
Quil'auteur de la pull requestle mainteneur

Les fragments restent hors de docs/ : ce sont des notes de travail, réécrites et regroupées dans la page de la version.

D'une pull request à une version

Quand écrire un fragment

Pour tout changement visible ou utile en dehors de la pull request :

  • une fonctionnalité ou une page du site ;
  • un changement de l'API (route, champ, comportement) ;
  • un changement des données : nouvelle source, nouveau rattachement, correction de masse, nouvel enrichissement IA ;
  • un changement de méthodologie (calcul d'une statistique, d'une position, d'un classement) ;
  • un changement d'outillage qui touche les contributeurs.

Une pull request sans effet notable (refactor interne, correctif mineur, dépendance sans effet visible) porte à la place le label changelog:aucun.

Format d'un fragment

.changelog/sous-amendements.md :

Code
--- niveau: mineur # correctif | mineur | majeur type: fonctionnalite # fonctionnalite | correction | donnees | methodologie | api | outillage public: [citoyens, reutilisateurs] # citoyens | reutilisateurs | contributeurs pr: [96] # [] si la pull request n'existe pas encore --- Les sous-amendements sont reliés à leur amendement parent, sur le site et dans l'API (`amendementParent`, filtre par parent). Les amendements identiques sont regroupés.
  • Le nom du fichier est le sujet en kebab-case, unique ; pas de date, c'est la version qui date.
  • Une à trois phrases en français, au présent, compréhensibles sans connaître le code ; 600 caractères au plus.
  • Décrire l'effet pour le lecteur, pas l'implémentation ; citer la route ou le champ d'API concernés.
  • Dire ce qui est calculé ou produit par IA ; rester apartisan.
  • Une rupture d'API (type: api, niveau: majeur) dit aux réutilisateurs quoi faire : « À faire de votre côté : … ».

pnpm changelog:check vérifie le format ; la CI vérifie aussi qu'une pull request ajoute un fragment ou porte le label changelog:aucun.


🏷️ Publier une version

Réservé au mainteneur. Merger une pull request ne publie jamais de version.

  1. Préparer, sur une branche chore/release-vX.Y.Z à jour de master :

    TerminalCode
    pnpm changelog:prepare --essai # aperçu : version calculée, PR sans fragment, commits hors PR pnpm changelog:prepare # écrit la page, monte les package.json, consomme les fragments

    La version suit le niveau le plus haut des fragments (--niveau pour monter d'un cran, --version 1.0.0 pour un choix explicite).

  2. Rédiger la page docs/03-changelog/vX-Y-Z.mdx, sur le modèle des versions précédentes :

    • la description résume les thèmes du palier ;
    • En bref : quelques lignes et un tableau « Pour qui / Ce qui change » ;
    • faits marquants : une section par nouveauté importante, expliquée avec un lien vers le site, un schéma Mermaid ou un exemple d'appel à l'API ;
    • Notes complètes : les fragments regroupés par thème. Elles deviennent le message du tag.

    Puis pnpm docs:nav et pnpm docs:validate.

  3. Pull request chore(release): vX.Y.Z, relue puis mergée.

  4. Taguer le commit de merge, puis créer la GitHub Release avec les mêmes notes :

    TerminalCode
    node scripts/changelog/tag-message.mjs vX.Y.Z > /tmp/tag.txt git tag -a vX.Y.Z -F /tmp/tag.txt && git push origin vX.Y.Z gh release create vX.Y.Z --title "vX.Y.Z" --notes-file /tmp/tag.txt

Règles des tags :

  • un tag annoté vX.Y.Z, sur master, posé sur le commit de la version ;
  • un tag publié n'est jamais déplacé ni supprimé : une erreur se corrige par une nouvelle version ;
  • pas de branche de maintenance : une correction urgente passe par un fragment correctif et une version vX.Y.Z+1 depuis master.

Les pages des versions déjà taguées se régénèrent depuis leurs tags avec node scripts/changelog/from-tags.mjs.

Version v0.5.0
On this page
  • 🗓️ Les versions en un coup d'œil
  • 🔢 Ce que signifie le numéro
  • 🧩 Deux niveaux : fragments et versions
    • Quand écrire un fragment
    • Format d'un fragment
  • 🏷️ Publier une version
Markdown