Aller au contenu

Standards pour les développeurs

Conventions de travail communes aux 5 dépôts (ScoroOdkBridge, lcl-rapports, lcl-chatbot, lcl-labtracker, ScoroPost) et à ce dépôt de documentation. Le but : que n'importe qui reconnaisse à quoi sert une branche juste en lisant son nom, peu importe le dépôt.

Nommage des branches

Trois niveaux, du plus stable au plus court terme :

Branche Créée à partir de Rôle
main — Code en production. Ne reçoit que des fusions depuis dev, jamais de commit direct.
dev main Intégration. Les branches de travail se fusionnent ici en premier ; c'est ce qui est validé avant d'aller en production (voir Infrastructure et la règle tester sur dev avant prod du CLAUDE.md du dossier parent).
<type>/KAN-XXX-description-courte dev Une branche par ticket. Fusionnée dans dev, puis supprimée une fois fusionnée. 
gitGraph
    commit id: "release"
    branch dev
    checkout dev
    commit id: "intégration"
    branch feature/KAN-123-nouveau-rapport
    checkout feature/KAN-123-nouveau-rapport
    commit id: "travail"
    checkout dev
    merge feature/KAN-123-nouveau-rapport
    checkout main
    merge dev

dev (branche Git) ≠ dev (environnement Coolify)

Ne pas confondre les deux : la branche Git dev décrite ici existe dans les 5 dépôts. L'environnement Coolify lcl-chatbot-dev (voir Infrastructure) est un déploiement séparé propre à lcl-chatbot, qui tourne habituellement à partir de cette branche dev mais reste un concept distinct (c'est un serveur qui roule le code, pas une branche du dépôt).

Format d'une branche de travail

<type>/KAN-XXX-description-courte
  • KAN-XXX : le numéro du ticket (ex. KAN-142), pour retrouver facilement de quoi la branche parle.
  • description-courte : quelques mots en minuscules séparés par des tirets, qui résument le ticket (pas obligé de recopier le titre exact).

  • <type> : ce que fait la branche. Les plus utilisés :

    Type Utilisation
    feature/ Nouvelle fonctionnalité
    fix/ Correction de bug
    chore/ Tâche sans impact fonctionnel (dépendances, config, ménage)
    docs/ Documentation seulement (ex. ce dépôt)

Exemples :

feature/KAN-118-alerte-non-conformite
fix/KAN-142-proctor-correction
docs/KAN-97-ajout-standards-dev

Fusion (merge)

Deux fusions distinctes, chacune avec sa propre validation — ne pas sauter d'étape même si le ticket semble simple.

1. Branche de travail → dev (aller)

  1. Créer la branche à partir de dev (pas de main).
  2. Développer, committer.
  3. Avant d'ouvrir la Pull Request, valider localement (voir le tableau ci-dessous selon le dépôt).
  4. Ouvrir la PR vers dev, jamais directement vers main.
  5. Une fois fusionnée, supprimer la branche de travail.

2. dev → main (chemin retour, mise en production)

C'est l'étape qui applique la règle tester sur dev avant prod : dev accumule plusieurs branches de travail fusionnées, donc revalider l'ensemble avant de le promouvoir en production, pas seulement le dernier changement.

  1. S'assurer que dev est à jour et build/tourne sans erreur.
  2. Revalider (voir tableau) — en particulier si plusieurs tickets se sont accumulés dans dev depuis la dernière mise en production.
  3. Ouvrir la PR dev → main.
  4. Après la fusion, redéployer dans Coolify (voir Infrastructure) et vérifier les logs de l'application pendant quelques minutes.
  5. En cas de problème en production, revenir à la version précédente via l'historique des déploiements Coolify plutôt que de pousser un correctif dans l'urgence.

Quoi valider, selon le dépôt

Dépôt Avant de fusionner (aller et retour)
lcl-labtracker Les 78 tests automatisés doivent passer — calculs certifiés (béton, granulats, Proctor), aucune erreur tolérée.
lcl-rapports Si le changement touche la mise en page d'un rapport : comparer les PDF générés aux 113 PDF de référence, image par image.
lcl-chatbot Valider sur l'environnement Coolify lcl-chatbot-dev avant de fusionner vers main/lcl-chatbot-prod. Si des PDF de normes ont changé, relancer l'ingestion (rien ne se propage automatiquement) et surveiller les crédits OpenAI/Anthropic avant des tests en masse.
ScoroOdkBridge Vérifier manuellement qu'aucune fiche ODK en double n'est créée (le fichier de suivi sur volume persistant fait foi) et que le compte de service ODK a toujours ses droits.
ScoroPost S'assurer que MAIL_REDIRECT_TO et ODK_FAKE_LINKS sont dans l'état voulu avant tout envoi réel (retirés en prod réelle, actifs en test).
lcl-docs (ce dépôt) .venv\Scripts\python -m mkdocs build sans erreur/lien cassé, et vérifier visuellement la page modifiée.

Note

Cette page documente une convention d'équipe, pas une contrainte imposée par un outil (aucune protection de branche automatisée n'est en place pour l'instant [à confirmer]). Elle vaut ce que vaut son respect par tout le monde.