feat: fait reposer le deploiement sur des versions taguees

README.md

@@ -35,6 +35,80 @@ make dev
 
 Ouvrir **http://localhost:5173** — le proxy Vite redirige `/api` vers le backend.
 
+## Tests
+
+```bash
+make test   # ruff check + pytest + vitest, soit exactement ce que la CI verifie
+```
+
+Les tests de non-regression des parseurs comparent l'extraction de PDF reels a
+des references figees. PDF (`data/`) et references (`tests/golden/`) contiennent
+des donnees personnelles et ne sont pas versionnes : ces tests se **sautent**
+d'eux-memes la ou le corpus est absent, CI comprise. Les lancer pour de vrai
+suppose donc un corpus local (cf. `tests/test_parsers_golden.py`).
+
+## Versions et cycle de vie
+
+La production heberge des donnees reelles : elle suit des **versions**, pas la
+pointe de `main`.
+
+### Ce qu'est une version
+
+Un tag git `vMAJEUR.MINEUR.CORRECTIF` (semver), pose sur `main`. Le meme numero
+est ecrit dans quatre fichiers, que l'outillage tient d'accord entre eux :
+`pyproject.toml`, `src/plesna_gerance/__init__.py`, `frontend/package.json` et
+`packaging/installer.iss` (version affichee par l'installeur Windows).
+
+Quand incrementer quoi :
+
+| Segment | Quand | Exemple |
+| --- | --- | --- |
+| CORRECTIF (`0.1.1`) | correction sans changement d'usage | un montant mal lu |
+| MINEUR (`0.2.0`) | nouvelle fonctionnalite, donnees existantes intactes | une nouvelle page |
+| MAJEUR (`1.0.0`) | rupture : migration de base ou changement d'usage a annoncer | refonte du referentiel |
+
+### Publier une version
+
+```bash
+make test                      # ce que la CI verifiera de toute facon
+make release VERSION=0.2.0     # aligne les 4 fichiers, commite, pose le tag
+git push origin main v0.2.0    # <- c'est ce push qui publie
+```
+
+`make release` **ne pousse pas** : le tag reste local tant qu'on ne l'a pas
+envoye, ce qui laisse le temps de relire le commit de version. Le script
+(`scripts/release.py`) refuse d'avancer hors de `main`, sur un arbre sale, ou
+si le tag existe deja — un tag publie ne se reecrit pas.
+
+### Ce que declenche le push d'un tag
+
+- **`.gitea/workflows/docker-publish.yml`** : lance d'abord les tests
+  (`ruff`, `pytest`, `vitest`), et seulement s'ils passent construit et publie
+  l'image sous **trois** tags — `0.2.0`, `0.2` et `0`. Epingler `0.2.0` fige le
+  deploiement a l'octet pres ; `0.2` laisse entrer les correctifs de la serie.
+- **`.github/workflows/build-windows.yml`** : construit l'executable et
+  l'installeur Windows (necessite un runner `windows-latest`).
+
+Un push sur `main` **sans tag** publie `latest` et `main` : utile pour essayer
+la pointe, jamais pour la production.
+
+### Deployer une version
+
+La version deployee est epinglee dans `.env`, lu par `docker-compose.yml` :
+
+```bash
+cp .env.example .env      # une seule fois
+# editer PLESNA_VERSION=0.2.0
+make docker               # pull + up -d
+```
+
+Revenir en arriere, c'est la meme manoeuvre : remettre le numero precedent dans
+`.env` et relancer `make docker`. Les donnees vivent dans le volume nomme
+`plesna-data`, independamment de l'image — un retour arriere d'image ne les
+touche pas. En revanche une version qui a **migre le schema** de la base ne se
+defait pas en changeant le numero : sauvegarder le volume avant une montee de
+version majeure.
+
 ## Production (Docker)
 
 Un **conteneur unique** : l'image embarque le frontend Vue builde, servi par
@@ -42,7 +116,7 @@ le backend FastAPI (API + interface web sur le meme port). Pas de nginx.
 
 L'image est **publiee par la CI Gitea** (`.gitea/workflows/docker-publish.yml`)
 sur `git.opytex.org/lafrite/plesna-gerance`. Le `docker-compose.yml` la **tire**
-directement (pas de build local) :
+directement (pas de build local), a la version epinglee dans `.env` :
 
 ```bash
 make docker          # podman-compose pull && podman-compose up -d