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 et dans la première entrée du 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 pour la procédure complète. Le résumé :

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