Contribuer

Aidez à bâtir MapleStats

MapleStats est un logiciel libre qui grandit une source à la fois. Vous pouvez aider sans écrire une ligne de code : signaler un chiffre erroné, proposer une source ou raconter comment vous l'avez utilisé. Si vous écrivez du code, cette page décrit tout le processus, du premier ticket jusqu'au site en ligne.

Façons d'aider

Signaler un chiffre erroné ou manquant

Ouvrez un ticket avec la question posée, l'appel d'outil et l'URL de la source indiquée dans la provenance du résultat. Un chiffre erroné est le signalement le plus utile qui soit.

Signaler un chiffre

Proposer une source

Nommez l'organisme ou le portail et indiquez où se trouvent ses données. La feuille de route énumère chaque source examinée jusqu'ici, y compris celles qui n'ont pas pu être ajoutées, et pourquoi.

Proposer une source · Feuille de route

Partager une étude de cas

Vous avez utilisé MapleStats pour un vrai travail ? Ouvrez un ticket avec la question, ce que l'agent a trouvé et les appels qu'il a faits. Les meilleurs exemples rejoignent les études de cas.

Partager une étude de cas

Les francophones aident aussi : chaque outil porte des mots-clés de recherche en français et chaque page est bilingue. Si une phrase sonne comme une traduction, ouvrez un ticket ou proposez une correction.

Le processus pour le code

Ouvrir d'abord un ticket

Dites ce que vous voulez ajouter ou corriger avant d'écrire du code, pour que personne ne fasse le travail en double et que l'approche soit convenue tôt. Pour une nouvelle source, donnez le lien vers la documentation de son API ou sa page de données.

Préparer le poste et lire AGENTS.md

Faites une bifurcation (fork) du dépôt, clonez-le et installez-le avec uv. Lisez ensuite AGENTS.md : c'est le guide de travail des personnes comme des agents. Il explique la structure d'un module, le contrat de réponse que suit chaque outil et trois lignes qui semblent superflues mais ne le sont pas.

Terminal

git clone https://github.com/dsanchezp18/maplestats-mcp.git
cd maplestats-mcp
uv sync

Travailler avec la vraie API

Une nouvelle source commence par une copie de modules/_example/ : des réponses typées qui portent leur provenance, des erreurs levées plutôt que renvoyées, et une docstring avec des mots-clés de recherche en anglais et en français. Avant de considérer un client comme terminé, appelez chacune de ses fonctions sur l'API réelle, avec des arguments réalistes. Les tests simulés prouvent seulement que le code fait ce que vous pensiez que l'API fait ; un audit de ce projet qui a appelé chaque outil en direct a trouvé neuf bogues que les simulations avaient manqués.

Le tester et le répertorier

Ajoutez des tests unitaires simulés pour le client (avec pytest-httpx), qui couvrent les particularités de la vraie API, et une étape de test en direct pour chaque outil dans scripts/smoke_test_modules.py. Ajoutez ensuite le module à SOURCES dans scripts/build_site.py, pour que le site puisse le nommer. Un test échoue si l'un ou l'autre manque.

Lancer les vérifications

Les quatre mêmes vérifications que l'intégration continue. Les quatre doivent réussir avant l'examen d'une demande de fusion.

Terminal

uv run ruff check src tests scripts
uv run ruff format --check src tests scripts
uv run pyright
uv run pytest -q

Ouvrir une demande de fusion

Décrivez ce qui a changé et comment vous l'avez vérifié auprès de la source en direct. L'intégration continue lance les vérifications sous Python 3.12 et 3.13, et une personne responsable examine le changement. Les demandes courtes et ciblées sont examinées et fusionnées plus vite.

Après la fusion

Une fois la fusion faite dans la branche principale, l'intégration continue relance les vérifications et, si elles réussissent, le site se reconstruit et se redéploie : un nouvel outil apparaît dans la page Outils et dans la recherche. Les données des études de cas, elles, ne changent que lorsque quelqu'un lance scripts/capture_cases.py et valide les nouveaux enregistrements. Chaque lundi, une tâche planifiée lance les tests en direct sur les vraies API, pour repérer un changement en amont même quand le code n'a pas bougé.

Avec un agent de programmation

Le dépôt est conçu pour les agents de programmation. Dirigez d'abord le vôtre vers AGENTS.md (le fichier CLAUDE.md du dépôt y renvoie aussi) ; il suivra le même processus et lancera les mêmes vérifications.

Lis AGENTS.md dans ce dépôt, puis ajoute un module pour [la source] en le suivant.

Règles de base

Les contributions sont publiées sous la licence MIT du projet.
Les données restent chez leurs éditeurs. MapleStats centralise l'interface, pas les données : ne versez pas de copies des données d'une source dans le dépôt.
Aucune clé d'API ni aucun identifiant dans le code. Toutes les sources actuelles fonctionnent sans.
L'anglais et le français ensemble : un outil sans mots-clés français est introuvable par une requête en français.