ObsiGate/docs/DELIVERY_WORKFLOW.md

Méthode de livraison ObsiGate — Definition of Done

Document de référence obligatoire. À consulter au début de chaque tâche (fonctionnalité, correction de bug, refactor) et à respecter avant de considérer le travail terminé. Référencé par AGENTS.md, la Roadmap et CONTRIBUTING.md.

---

1. Principe : une seule méthode, toujours la même

Quelle que soit la demande, on suit le même cycle. Une tâche n'est jamais « terminée » tant que la checklist du §5 n'est pas entièrement verte, CI compris.

---

2. Où vit l'information (source unique de vérité)

Fichier	Rôle	Quand le mettre à jour
docs/ROADMAP.md	Travail à venir (🔵 En cours + ⚪ Backlog) + index du complété	Au début (statut) et à la fin (index)
CHANGELOG.md	Historique officiel par version (Keep a Changelog)	À chaque livraison, dans [Unreleased]
docs/features/<slug>.md	Conception / spec détaillée d'une grosse feature	Quand l'item est livré
docs/archive/COMPLETED_v1-v2.md	Détail des items courts livrés	Quand l'item est livré
docs/ISSUES_TODOLIST.md	Registre des bugs / TODO	À chaque bug (statut + correctif/commit)
docs/DEVELOPMENT_AND_RELEASES.md	Build local & publication des releases	Quand le process change
Guides docs/*_GUIDE.md, docs/SPEC_*.md, docs/*_ARCHITECTURE*.md	Conception technique détaillée	Si le domaine concerné change
Guide intégré (i18n frontend/locales/fr.json + en.json)	Guide utilisateur in-app	Si impact utilisateur
README.md / README.fr.md	Documentation grand public	Si impact utilisateur
Docstrings + response_model (backend/) + backend/openapi_docs.py	Documentation API	Si endpoint ajouté/modifié

Règle d'or : un fait = un seul fichier. On ne duplique jamais le détail entre roadmap et changelog.

---

3. Choisir le bon registre

• Nouvelle fonctionnalité → item #NN dans la Roadmap (⚪ Backlog → 🔵 En cours).
• Bug → ligne dans ISSUES_TODOLIST.md (statut 🔴 ouvert → 🟠 en cours → 🟢 corrigé → ✅ vérifié).
• ID stable : un #NN ou BUG-NNN ne change jamais et n'est jamais réutilisé. C'est la clé de jointure entre roadmap, changelog, issues et commits.

---

4. Workflow standard (dans l'ordre)

1. Cadrer — identifier l'ID (#NN / BUG-NNN), lire la Roadmap et ISSUES_TODOLIST.md, passer le statut à 🔵 En cours / 🟠 en cours avant de coder.
2. Implémenter — respecter les standards de CONTRIBUTING.md : typage, docstrings, response_model, CSS variables, i18n FR/EN, sécurité _resolve_safe_path().
3. Tester — écrire/étendre les tests unitaires. Un correctif sans test de non-régression n'est pas terminé.
4. Vérifier en local — exécuter les commandes du §6.
5. Documenter — CHANGELOG [Unreleased], Roadmap / ISSUES, fiche feature ou archive, guide utilisateur + i18n FR/EN, README si besoin, OpenAPI si API.
6. Commit — message conventionnel (feat:, fix:…) référençant #NN / BUG-NNN.
7. Push puis vérifier le CI vert (jobs lint, test, security, build, e2e).
8. Clôturer — statut 🟢 corrigé / index ✅ posé par l'IA ; l'utilisateur valide (✅ vérifié).

---

5. Checklist « Definition of Done »

Code

• Comportement conforme à la demande
• Standards CONTRIBUTING respectés
• Aucun secret / clé committé
• i18n FR et EN si texte d'interface

Tests

• Tests unitaires ajoutés ou mis à jour (backend pytest / frontend Node)
• pytest vert en local
• ruff + mypy : 0 erreur
• Tests frontend verts (validate-imports + unit + JSDOM ciblés)
• E2E Playwright si flow UI critique touché

Documentation

• CHANGELOG.md → [Unreleased] (section Ajouté / Modifié / Corrigé)
• docs/ROADMAP.md → statut mis à jour + ligne dans l'index « Complété »
• Fiche docs/features/<slug>.md ou docs/archive/ si l'item est livré
• docs/ISSUES_TODOLIST.md → statut + colonne « Correctif / Commit » (si bug)
• Guide d'utilisation (i18n) + README FR/EN si impact utilisateur
• OpenAPI / docstrings + response_model si API

Livraison

• Commit conventionnel référençant l'ID
• Push effectué
• CI vert : lint → test → security → build → e2e

---

6. Commandes de vérification locale

# Backend
.\.venv\Scripts\python.exe -m pytest tests/
.\.venv\Scripts\python.exe -m ruff check backend/
.\.venv\Scripts\python.exe -m mypy backend/ --ignore-missing-imports

# Frontend
node tests/frontend/validate-imports.mjs
node tests/frontend/unit.test.mjs
# tests JSDOM ciblés, ex :
node tests/frontend/pane-manager.test.mjs

# E2E (si UI)
npx playwright test

Les mêmes vérifications tournent dans le CI Gitea (.gitea/workflows/ci.yml) : jobs lint, test, security, build, e2e.

---

7. Versionnement & release

• SemVer MAJOR.MINOR.PATCH ; tags Git vX.Y.Z ; source de vérité = CHANGELOG.md.
• Lors d'une publication : déplacer [Unreleased] vers [X.Y.Z] — date, tagger, builder et publier (procédure détaillée dans DEVELOPMENT_AND_RELEASES.md).
• Ne jamais réécrire une version déjà publiée dans le CHANGELOG.

---

8. À ne jamais faire

• Marquer une tâche terminée sans tests verts ni CI vert.
• Committer sans mettre à jour CHANGELOG.md et le registre concerné (Roadmap / Issues).
• Dupliquer le détail entre Roadmap et CHANGELOG.
• Réutiliser un ID #NN / BUG-NNN.
• Pousser des secrets, clés ou tokens.