151 lines
7.8 KiB
Markdown
151 lines
7.8 KiB
Markdown
# 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.
|