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
`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`	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 : écrire dans `[Unreleased]` (publié en `[X.Y.Z] — date` par le bump)
`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)

Cadrer — identifier l'ID (#NN / BUG-NNN), lire la Roadmap et ISSUES_TODOLIST.md, passer le statut à 🔵 En cours / 🟠 en cours avant de coder.
Implémenter — respecter les standards de CONTRIBUTING.md : typage, docstrings, response_model, CSS variables, i18n FR/EN, sécurité _resolve_safe_path().
Tester — écrire/étendre les tests unitaires. Un correctif sans test de non-régression n'est pas terminé.
Vérifier en local — exécuter les commandes du §6.
Documenter — CHANGELOG [Unreleased], Roadmap / ISSUES, fiche feature ou archive, guide utilisateur + i18n FR/EN, README si besoin, OpenAPI si API.
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.
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).
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

# 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 (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.

7.8 KiB Raw Blame History

Méthode de livraison ObsiGate — Definition of Done