# 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`](../AGENTS.md), la [Roadmap](./ROADMAP.md) et [CONTRIBUTING.md](./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 |
|---|---|---|
| [`VERSION`](../VERSION) (racine) | **Version livrée** — source unique de vérité (SemVer `MAJEUR.MINEUR.CORRECTIF`) | Automatiquement à chaque commit (hook `.githooks/prepare-commit-msg`) |
| [`docs/ROADMAP.md`](./ROADMAP.md) | Travail **à venir** (🔵 En cours + ⚪ Backlog) + index du complété | Au début (statut) et à la fin (index) |
| [`CHANGELOG.md`](../CHANGELOG.md) | Historique officiel par version (Keep a Changelog) | À chaque livraison : écrire dans `[Unreleased]` (publié en `[X.Y.Z] — date` par le bump) |
| [`docs/features/<slug>.md`](./features/) | **Conception / spec détaillée** d'une grosse feature | Quand l'item est livré |
| [`docs/archive/COMPLETED_v1-v2.md`](./archive/COMPLETED_v1-v2.md) | Détail des items courts livrés | Quand l'item est livré |
| [`docs/ISSUES_TODOLIST.md`](./ISSUES_TODOLIST.md) | Registre des **bugs / TODO** | À chaque bug (statut + correctif/commit) |
| [`docs/DEVELOPMENT_AND_RELEASES.md`](./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](./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` : le
   préfixe détermine l'incrément SemVer de `VERSION` (MAJEUR / MINEUR / CORRECTIF), appliqué
   automatiquement par le hook `.githooks/prepare-commit-msg`.
7. **Push** puis **vérifier le CI vert** (jobs `lint`, `test`, `security`, `build`, `e2e`) ; le
   tag `vX.Y.Z` de la version livrée est publié avec la branche (`push.followTags`).
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
- [ ] `VERSION` incrémenté et dérivés synchronisés (automatique via le hook ; `tests/test_version.py` vert)
- [ ] `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

```powershell
# 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

- **Source unique de vérité : le fichier [`VERSION`](../VERSION)** (racine du dépôt), au format
  `MAJEUR.MINEUR.CORRECTIF` (SemVer). Il est incrémenté **automatiquement à chaque commit** par
  le hook versionné `.githooks/prepare-commit-msg` — `!:` / `BREAKING CHANGE` → **MAJEUR**, `feat` →
  **MINEUR**, tout le reste → **CORRECTIF** — puis tagué `vX.Y.Z` par `.githooks/post-commit`
  (tag publié au push grâce à `push.followTags`). Installation une fois par clone :
  `scripts/install-hooks.sh`.
- Le même commit resynchronise les dérivés : `package.json`, desktop Tauri (`tauri.conf.json`,
  `Cargo.toml`, `Cargo.lock`), `README.md`/`README.fr.md`, `docs/ROADMAP.md`, et publie la
  section `[Unreleased]` du `CHANGELOG.md` en `[X.Y.Z] — date`.
- Le backend (`backend/version.py`), l'image Docker (`COPY VERSION`) et le desktop Tauri lisent
  ce fichier : la version affichée par l'UI (`/api/health` → header, boîte À propos) suit donc
  chaque livraison.
- **Garde-fou** : `tests/test_version.py::TestRepoVersionAlignment` échoue dès qu'un dérivé
  diverge de `VERSION` (numéro codé en dur, CHANGELOG sans section, README non resynchronisé).
- Bump manuel si besoin : `scripts/bump_version.py --dry-run|--minor|--set X.Y.Z|--push`.
  Commit sans incrément (cas exceptionnel) : `SKIP_VERSION_BUMP=1 git commit …`.
  Le rattachement des fichiers au commit se fait par un `--amend` immédiat (commit non encore
  poussé) : le SHA affiché par `git commit` est donc remplacé par celui de l'amend — `git log`,
  `HEAD` et le tag `vX.Y.Z` restent, eux, alignés sur la version livrée.
- **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.