Workflow de développement¶

Cette page documente la manière dont le développement de CTLD est mené : le processus de backlog, le Git Flow, le développement piloté par les tests, la construction et les portes de qualité, ainsi que les skills d'écriture utilisés pour conduire le travail. C'est le manuel opératoire des contributeurs — le « comment nous travaillons », en complément du « comment c'est construit » du reste de cette section.

Processus de backlog¶

CTLD n'utilise pas les GitHub Issues comme tracker. Il utilise un backlog markdown local sous .backlog/, versionné avec le code. Cela maintient la planification dans le même flux de revue que le changement lui-même.

Un lot = un répertoire .backlog/<LOT-ID>/. Un lot est une unité de travail cohérente qui est livrée sous forme d'une seule branche et d'une seule pull request.
PRD — .backlog/<LOT-ID>/PRD.md contient l'énoncé du problème, la solution, les décisions, le périmètre, la définition de « terminé » et les notes de hors-périmètre. Il cite son ou ses ADR le cas échéant.
Tickets — .backlog/<LOT-ID>/tickets/<NN>-<slug>.md, numérotés à partir de 01 dans l'ordre des dépendances, sous forme de tranches verticales « tracer-bullet ».
Index — .backlog/README.md est un tableau maintenu à la main de chaque lot et de son statut (pas de générateur).
Archivage — les lots clos depuis plus de trois jours sont compactés dans .backlog/archive/<LOT-ID>.md, en préservant le tableau des tickets.

Convention d'identifiant de lot¶

Préfixes sémantiques : FEAT-*, FIX-*, DOC-*, TOOLING-*, UX-*, RELEASE. Par exemple FEAT-JTAC-DRONE-ORBIT, FIX-MENU-REFRESH, TOOLING-INTEGRATION-TEST-RUNNER.

Vocabulaire des statuts¶

Une ligne Status: en tête de chaque fichier PRD / ticket fait foi pour son état de cycle de vie ; .backlog/README.md la reflète dans l'index.

Statut	Emoji	Signification
ready	⬜	prêt à être pris en charge
in-progress	🔄	en cours de traitement
waiting-human	🧑	nécessite une décision humaine ou plus d'informations
done	✅	livré
wontfix	🚫	délibérément non traité

La configuration du tracker vit dans dev/agents/issue-tracker.md ; le vocabulaire des statuts dans dev/agents/triage-labels.md.

Git Flow¶

Le travail se déroule sur des branches feature/* ou fix/* issues de develop. Ne jamais committer directement sur develop ou master.
Une branche / une PR par lot — tous les tickets d'un lot atterrissent ensemble, même si le backlog les découpe individuellement.
Les commits suivent les Conventional Commits en anglais.
develop est la branche d'intégration ; master est réservée aux merges de jalons stables et n'est câblée à aucune automatisation de release. Voir Processus de release ci-dessous.

Développement piloté par les tests¶

Toute logique nouvelle ou modifiée est livrée test-first : écrire une spec busted qui échoue, la faire passer, puis refactorer. La porte de couverture est un cliquet — la CI impose un plancher qui ne fait que monter, si bien que la couverture ne peut pas régresser.

Voir Construction et tests pour les commandes concrètes, le cliquet de couverture, la journalisation et la configuration de débogage.

Construction et portes de qualité¶

Livrable — seul CTLD.lua doit être du Lua 5.1 pur (DCS tourne en Lua 5.1 ; pas de syntaxe 5.2+). Il est généré par tools/build/merge_CTLD.ps1 et ne doit jamais être édité à la main ; reconstruire après tout changement dans src/.
Portes de CI (au push sur develop et sur les PR qui la ciblent) :
- lua-lint — vérification syntaxique avec luac5.1 -p.
- luacheck — --config .luacheckrc src/ doit être propre.
- tests busted + cliquet de couverture.
- scan de secrets gitleaks.
- Build de fusion — CTLD.lua est produit d'une seule manière canonique à partir de src/.
Docs — quand un comportement ou une interface change, les pages docs/ concernées changent dans la même PR.

Processus de release¶

Les releases sont pilotées par tag, pas par branche — aucun push sur develop ou master ne publie quoi que ce soit. Le skill Claude Code interactif release (invoqué avec /release) pilote tout le processus pas à pas : interview de consolidation, RELEASE_NOTES.md orienté communauté, incrément de version, mise à jour du CHANGELOG selon le canal, rebuild, PR de release, et les commandes de tag finales. Les étapes qu'il déroule :

Sur une branche release/x.y.z créée depuis develop : rédiger RELEASE_NOTES.md, incrémenter ctld.VERSION dans src/CTLD_config.lua, mettre à jour CHANGELOG.md, rebuilder CTLD.lua. La PR cible develop.
Après le merge, pousser le tag published-vx.y.z manuellement — cela déclenche .github/workflows/release.yml, qui rebuild et publie la GitHub Release avec CTLD.lua attaché.

Deux canaux, choisis par la chaîne de version :

Pre-release (x.y.z-rcN, ex. 2.0.0-rc1) → publiée en tant que pre-release GitHub. ## [Unreleased] reste ouvert (les correctifs post-rc continuent d'y atterrir) et le tag flottant published-latest n'est pas déplacé — ceux qui le suivent restent sur la dernière stable.
Stable (x.y.z) → une release normale ; ## [Unreleased] est figé en ## [x.y.z] — date, et published-latest est avancé jusqu'à elle — un pointeur de téléchargement permanent vers la « dernière stable ».

Builds de développement¶

Une release reste la seule chose qu'on demande à un concepteur de mission de télécharger — mais entre deux releases, il faut bien quelque chose à donner à un testeur. Chaque fusion dans develop déclenche donc .github/workflows/dev-build.yml, qui produit un ctld-tools.exe complet à partir de ce commit (interface web, schéma, catalogue par défaut et moteur issus de la même source) et le publie deux fois :

en artefact d'action (ctld-tools-dev, conservé 14 jours) — traçable par exécution, mais son téléchargement exige une session GitHub et il arrive dans un .zip ;
en pré-version flottante dev, réécrite à chaque fusion — téléchargement anonyme, lien stable, l'.exe directement. C'est celle qu'on envoie.

Un tel build inscrit son commit dans ctld.VERSION : --version affiche 2.0.0-rc6-a1b2c3d, tout comme le rapport d'installation et la copie du moteur dans la mission — un rapport de bug nomme donc son build. Le suffixe vient de merge_CTLD.ps1 -VersionSuffix, utilisé par ce seul workflow : un build local et une release conservent la version écrite dans src/CTLD_config.lua.

Le tag dev ne correspond pas à published-v* : le rafraîchir ne déclenche jamais le workflow de release, et published-latest continue de désigner la dernière version stable.

Ce n'est pas une release

Un build de développement n'a ni notes de version, ni documentation publiée propre, ni garantie au-delà de la CI passée sur son commit. En donner un à un concepteur de mission qui n'a rien demandé, c'est se condamner à déboguer une version que personne ne sait identifier.

Skills d'écriture¶

Le programme de ré-outillage est mené avec trois skills d'écriture agnostiques du tracker (ils écrivent dans le .backlog/ local, pas dans GitHub) :

Skill	Rôle dans le flux
`grill-with-docs`	Éprouve un plan face au modèle de domaine du projet et aux décisions documentées (`CONTEXT.md`, ADR), affine la terminologie et met à jour cette documentation au fil de l'eau à mesure que les décisions se cristallisent. Utilisé avant de s'engager sur une conception.
`to-prd`	Transforme la conversation/le contexte qui en résulte en un `PRD.md` pour le lot. Utilisé pour ouvrir un lot.
`to-issues`	Découpe le plan/PRD en tickets indépendamment saisissables sous forme de tranches verticales « tracer-bullet ». Utilisé pour remplir le `tickets/` d'un lot.

Séquence typique pour un nouveau lot : grill-with-docs (converger sur la conception) → to-prd (rédiger le PRD) → to-issues (découper les tickets) → implémenter sur une branche feature/* (TDD) → PR vers develop.

Séquence de bout en bout par défaut¶

Synchroniser develop (git pull --ff-only).
Créer le lot dans .backlog/ (PRD + tickets).
Créer la branche (feature/* ou fix/*).
Implémenter avec les tests (TDD) ; reconstruire CTLD.lua si src/ a changé ; mettre à jour docs/.
Lancer busted tests/ci/ et luacheck.
Mettre à jour CHANGELOG.md [Unreleased].
Committer + pusher ; ouvrir une PR vers develop.
Traiter la revue / la CI ; merger ; revenir à develop.