Guide de contribution

Ce guide décrit comment contribuer à Sites Conformes : ce qu’on attend d’une contribution, le processus pour la proposer, et les conventions de code à respecter.

La mise en place de l’environnement de développement (outils, dépôt, configuration, base de données) est décrite à part, dans Installer le projet en local.

Nos principes

Une contribution prête à être intégrée respecte les points suivants :

  • Langue du code : les identifiants (variables, fonctions, classes) et les commentaires sont écrits en anglais ; les textes affichés à l’utilisateur utilisent le système de Traductions, avec l’anglais pour langue par défaut. La documentation et les PR sont à rédiger en français.

  • Nommage et style : conventions Python/Django standard (snake_case pour les fonctions et variables, PascalCase pour les classes). L’ordre des imports (isort) et le formatage (black, 119 colonnes) sont appliqués automatiquement par les pre-commit hooks.

  • Tests : toute fonctionnalité est couverte par des tests automatisés, et l’ensemble de la suite passe sans erreur.

  • Accessibilité : l’application vise la conformité au RGAA v4.1 — équivalents textuels, contrastes suffisants, navigation au clavier, balisage sémantique, utilisation à 200 % de zoom, formulaires correctement étiquetés. Les contributions doivent respecter ces critères pour être approuvées.

  • CSS : utilisez autant que possible les classes du Système de design de l’État (via django-dsfr) plutôt que du style maison.

  • Documentation : la documentation technique et utilisateur est mise à jour si nécessaire.

Avant toute mise en production, l’ensemble est passé en revue via la Définition du fini, qui détaille cette liste point par point.

Proposer une contribution

L’ensemble des travaux en cours est à retrouver sur la roadmap. Celle-ci reflète les intentions et décisions prises dans le cadre du comité Produit du Club Contributeurs.

Si l’évolution que vous souhaitez ne s’y trouve pas, n’hésitez pas à venir en discuter sur Tchap dans le canal Sites Conformes ou ouvrir une issue sur Github, nous pourrons vous orienter et en discuter avant que vous entamiez un travail plus important.

  1. Créez une branche dédiée à partir de main, nommée <votre-identifiant>/<description-courte> — l’identifiant est votre nom d’utilisateur GitHub (ou vos initiales), et la description est en anglais, en minuscules avec des tirets. Exemple : lucie/fix-breadcrumb-rgaa.

  2. Développez en respectant les principes ci-dessus.

  3. Vérifiez localement avant de soumettre : just quality (ruff + black), puis just test.

  4. Ouvrez une pull request sur le dépôt numerique-gouv/sites-conformes. GitHub pré-remplit la description avec le modèle de PR du dépôt : complétez-le. Rédigez le titre en français — il sert à générer les notes de version (release notes) en français.

  5. Une fois la PR prête, assignez un·e relecteur·rice : Sylvain Boissel (Ash-Crow) ou Lucie Laporte (Luzzzi).

Note

Messages de commit : rédigez un message court et explicite. Il n’y a pas de format strict imposé. Les pull requests sont généralement intégrées en squash, avec ajout automatique du numéro de PR.

Améliorer la documentation

Cette documentation est perfectible, et l’enrichir est une contribution à part entière — au même titre que le code. Corriger une coquille, clarifier une étape, ajouter un cas d’usage ou une question de FAQ : tout est bienvenu.

Ses sources sont les fichiers Markdown du dossier docs/, et le site est construit avec Sphinx. Modifiez le fichier .md concerné et ouvrez une pull request, exactement comme pour du code.

Pour prévisualiser vos changements en local :

just docs

La commande construit la documentation, l’ouvre dans votre navigateur et la reconstruit automatiquement à chaque sauvegarde. Pour une simple construction ponctuelle (sans serveur), utilisez just docs-build, qui écrit le HTML dans docs/_build/html/.

Échanger entre développeurs

Si vous souhaitez contribuer activement, faites-nous signe pour rejoindre notre canal Tchap dédié aux développeurs, où l’on discute des évolutions et des besoins de Sites Conformes.

Contactez l’équipe à contact@sites.beta.gouv.fr ou depuis le salon Tchap public pour y être ajouté·e.

Lancer les tests

Les tests unitaires se lancent avec just test.

Cela lance les tests en parallèle pour gagner du temps, mais en cas d’échec, il est possible de les lancer séquentiellement via just unittest.

Vous pouvez également générer un rapport sur la couverture de tests :

just coverage

Pour toutes ces commandes, il est possible de cibler une application Django spécifique, par exemple :

just test sites_conformes.core
just unittest sites_conformes.blog
just coverage sites_conformes.events

Style de code et pre-commit

Nous utilisons ruff et black pour assurer un formatage cohérent du code sur l’ensemble du projet.

Pour vérifier son code, on peut intégrer le linter adapté à son IDE ou lancer la commande suivante :

just quality

Pour que cette vérification soit faite systématiquement, nous utilisons des pre-commit hooks.

Ils doivent être installés via :

pre-commit install

Il est possible de faire une passe manuelle sur l’ensemble du code via :

pre-commit run --all-files

Ajouter une dépendance

Le projet gère ses dépendances avec uv (fichiers pyproject.toml et uv.lock).

Pour ajouter un paquet :

uv add <paquet>

Pour un paquet ne servant qu’au développement, par exemple debug-toolbar :

uv add --dev <paquet>

Pensez à committer le uv.lock mis à jour avec votre modification.

Outils d’audit optionnels

cloc

La recette just cloc compte les lignes de code par application. Elle nécessite l’outil cloc.