docs/explanation/versioning.md

# Politique de versionning

> Comment Picarones numérote ses versions, et pourquoi.

## Résumé

Picarones suit **Semantic Versioning 2.0.0** strict :
`MAJOR.MINOR.PATCH` avec suffixes pré-release PEP 440 (`-rc1`,
`-beta1`, `-alpha1`).

**État courant** : `0.9.0` — phase pré-1.0.  Architecture stable,
surface fonctionnelle en construction.

**Cible** : `1.0.0` — release publique avec UI, rapport refondu et
parité des importeurs livrés.

---

## SemVer pré-1.0 : qu'est-ce que ça change ?

En `0.x`, SemVer autorise **les ruptures sans préavis**.  Picarones
les annonce explicitement dans le `CHANGELOG.md` mais ne garantit
pas de période de dépréciation.  C'est précisément l'intérêt du
pré-1.0 : pouvoir corriger l'API publique sans empêcher la
progression.

Concrètement :

- les schémas JSON (`BenchmarkResult`, `run_manifest.json`,
  `pipeline_results.jsonl`, `view_results.jsonl`) **peuvent évoluer**
  entre `0.9.x` et `0.10.x` ;
- les noms de paramètres CLI **peuvent changer** ;
- les endpoints HTTP **peuvent être renommés ou retirés** ;
- les contrats internes (Pydantic models de `picarones.domain`)
  **peuvent être modifiés**.

Chaque rupture est documentée dans le `CHANGELOG.md` sous la section
`### BREAKING`.

À partir de `1.0.0`, la politique se durcit : période de
dépréciation minimum d'une mineure, retrait à la majeure suivante.

---

## Mapping version ↔ tag git

Le numéro de version est dérivé du **tag git** par
`setuptools_scm`.  Pas de version codée en dur dans `pyproject.toml`.

| Contexte | Version produite |
|---|---|
| Tag `v0.9.0` posé sur un commit | `0.9.0` |
| 5 commits après `v0.9.0` (sans nouveau tag) | `0.9.1.dev5+g<sha>` |
| Tag `v0.10.0-rc1` | `0.10.0rc1` (PEP 440) |
| Sans aucun tag (tarball, repo neuf) | `0.9.0` (fallback) |

Le scheme `setuptools_scm` est `guess-next-dev` : les builds
intermédiaires suggèrent un patch à venir (`0.9.1.devN`).  Un bump
de mineure (`0.10.0`) ou majeure (`1.0.0`) est **toujours explicite**
via un nouveau tag git.

Le `fallback_version` de `pyproject.toml` est synchronisé avec
`picarones/domain/_version_fallback.py:FALLBACK_VERSION`.  Un test
d'architecture (`tests/architecture/test_single_version_source.py`)
vérifie cette cohérence.

---

## Roadmap vers 1.0.0

La sortie de `1.0.0` est conditionnée à la livraison de :

1. **Surface UI complète** — exposition de tous les champs du modèle
   `BenchmarkRunRequest`, refonte du rapport HTML, parité fonctionnelle
   avec la CLI (`compare`, `robustness`, `history`).
2. **Parité importeurs corpus** — IIIF, Gallica, eScriptorium accessibles
   depuis l'UI web (en plus de HTR-United et HuggingFace déjà présents).
3. **Refonte rapport HTML** — passage à l'IA 4 onglets (Overview / Engines
   / Documents / Crosses) en gardant la stack Jinja2.

Les versions intermédiaires `0.10.0`, `0.11.0`, etc. peuvent être
publiées au fil du chantier ; elles sont des jalons techniques, pas
des releases publiques.

---

## Pourquoi `0.9.0` plutôt que `2.0.x` ou `3.0.0` ?

L'historique interne du projet utilisait une dénomination « v2.0 »
pour désigner l'aboutissement du rewrite architectural en 8 couches
(mai 2026).  Cette dénomination reflétait un cycle de refactor
interne, pas une maturité fonctionnelle publique : à ce moment, le
projet n'avait ni interface utilisateur finalisée, ni parité
importeurs, ni rapport refondu.

Le repositionnement en `0.9.0` (mai 2026) aligne le numéro de
version sur la maturité réelle : architecture solide, surface
fonctionnelle en construction.  La sortie de `1.0.0` deviendra un
événement public marquant (UI complète, rapport refondu, parité
importeurs), ce qui correspond à l'usage habituel d'un saut
`0.x → 1.0`.

Ce choix est documenté dans la note de repositionnement de
[`docs/archive/README.md`](../archive/README.md) et dans la première
entrée du [`CHANGELOG.md`](../../CHANGELOG.md) post-repositionnement.

---

## Source unique de vérité (anti-dérive)

La version courante est définie à **un seul endroit** : le tag git le
plus récent, lu par `setuptools_scm`.

Le fallback (utilisé en l'absence de tag) est défini à **un seul
endroit** : `picarones/domain/_version_fallback.py:FALLBACK_VERSION`.  La
constante équivalente `fallback_version` dans `pyproject.toml` doit
rester synchronisée — un test d'architecture le vérifie.

**Règle de codage** : interdiction de coder un numéro de version en
dur ailleurs que dans ces deux fichiers.  Tout consommateur doit
lire `picarones.__version__` (ou ses équivalents internes
`_resolve_picarones_version()` pour les couches qui ne peuvent pas
importer le package racine).

---

## Procédure de release

Voir [`docs/operations/release-process.md`](../operations/release-process.md)
pour la procédure complète.  Le résumé :

```bash
# 1. Mettre à jour CHANGELOG.md (section ## [X.Y.Z] — YYYY-MM-DD)
git commit -am "docs(changelog): release 0.10.0"

# 2. Tag annoté
git tag -a v0.10.0 -m "Picarones 0.10.0"
git push origin main v0.10.0

# 3. Le workflow .github/workflows/release.yml déclenche
#    automatiquement build + TestPyPI + PyPI + Docker + GitHub Release.
```