🤝 Contribuer à la base commune de questions

Cette page s'adresse d'abord aux utilisateurs de Kutsum qui veulent partager des questions créées dans l'application. La méthode la plus simple consiste à préparer ses questions dans Kutsum, les exporter en YAML, puis les envoyer pour intégration dans la base commune.

👤 Contribuer depuis Kutsum

1. Créer vos questions dans l'application

Connectez-vous à Kutsum avec un compte enseignant.
Utilisez la page Créer des questions pour rédiger vos questions.
Renseignez les informations de taxonomie demandées dans l'application : discipline, niveau, thèmes et tags.
Vérifiez votre question dans l'interface, comme vous le feriez pour vos questions personnelles.

2. Si une valeur de taxonomie manque

Si vous ne trouvez pas le bon niveau, thème, tag ou la bonne discipline dans l'application, n'inventez pas une nouvelle valeur dans le YAML.
Faites plutôt une demande d'ajout à un mainteneur avant de contribuer vos questions.
Vous pouvez passer par un contact direct si vous n'êtes pas à l'aise avec GitLab.

3. Exporter vos questions

Une fois vos questions prêtes, exportez-les au format YAML depuis l'application.
Cet export correspond au bon point de départ pour une contribution.
Si vous passez par cette méthode, vous n'avez pas besoin d'exécuter de scripts de validation localement.

4. Envoyer votre contribution

Méthode simple : envoyez vos fichiers YAML ou vos questions à alexis.flesch@gmail.com.
Si vous utilisez GitLab : vous pouvez aussi proposer directement vos fichiers via une Merge Request.
Dans tous les cas, ajoutez un petit message indiquant au minimum la discipline, le niveau et le thème principal de votre contribution.

5. Contribuer des images

Si vous souhaitez proposer une image pour illustrer une question, vous pouvez l'envoyer avec votre contribution.
Formats conseillés : SVG de préférence, ou WebP avec une largeur maximale de 800 px.
Si possible, fournissez aussi une version claire et une version sombre.
Les images doivent être dans le domaine public ou sous licence CC-BY-SA.
Si l'image n'est pas dans le domaine public, indiquez clairement l'auteur, la source et la licence.

Exemple de fichier images.yaml pour une image :

- filename: "cercle.svg"
  title: "Cercle"
  type: "diagramme"
  description: "Un cercle (contour)."
  tags: ["forme", "cercle"]
  levels: ["CP", "CE1"]
  discipline: "mathématiques"

6. Revue et intégration

Les mainteneurs vérifieront la qualité, la cohérence et l'absence de doublons.
Si nécessaire, ils pourront vous recontacter pour clarifier un point de taxonomie, d'image ou de formulation.
Après validation, vos questions seront intégrées à la base commune et disponibles pour tous.

🛠️ Contribution avancée via le dépôt

Cette partie est utile si vous souhaitez contribuer directement dans le dépôt GitLab plutôt que d'envoyer simplement vos exports YAML.

👉 Voir la base de questions sur GitLab :

https://forge.apps.education.fr/alexisflesch/kutsum/-/tree/main/questions

La structure du dépôt est organisée par discipline, puis par niveau numéroté. Exemple : questions/mathématiques/05.CM2/.

1. Ajouter vos fichiers dans le dépôt

Placez vos fichiers YAML dans le dossier approprié.
Respectez l'organisation existante du dépôt.
Ouvrez ensuite une Merge Request en décrivant brièvement votre contribution.

2. Vérifier la validité si vous travaillez dans le dépôt

La validation minimale recommandée est ciblée sur le fichier que vous ajoutez.

Validez d'abord le YAML avec le validateur dédié :

python3 scripts/validate_questions_yaml.py --path questions/mathématiques/05.CM2/mon-fichier.yaml

Testez ensuite le passage par l'importeur si vous voulez vérifier le comportement réel d'import :

python3 scripts/import_questions.py --path questions/mathématiques/05.CM2/mon-fichier.yaml

Si vous avez modifié la taxonomie, réimportez-la explicitement :

python3 scripts/import_taxonomy.py --yes

Si vous avez ajouté ou renommé une image, synchronisez les images côté application :

cd app/backend && npm run sync-images

Cette partie avancée n'est pas nécessaire si vous contribuez simplement en exportant vos questions depuis Kutsum.

Merci pour votre contribution !