sanctuary-beta/docs/versioning.md

# Versionnement Sanctuary

Convention adoptée le 12 septembre 2026, ticket local **BETA-01**, branche
`codex/versioning-beta`. Le dernier socle alpha est `0.1.0-alpha.30.7` ;
la première version du nouveau cycle est **`beta.001`**.

Le nom du produit reste **Sanctuary** ; la version contient seulement
`beta.xxx`, pour obtenir `Sanctuary-beta.001.mrpack` et
`sanctuary-beta.001.jar` sans répéter le nom dans les métadonnées.

La préparation BETA-01 n’a pas été publiée séparément. À la demande du créateur,
la même version inclut ensuite [EXP-01, les quatre anciennes expéditions](expeditions-beta001.md),
sur `codex/ancient-expeditions-beta001`. Les observations BETA-01 ci-dessous
concernent la première étape, avant ce changement de jeu ; les essais finaux
d’EXP-01 sont consignés dans son propre document.

## Compteur de livraison

- Format exact en minuscules : `beta.xxx`, avec trois chiffres.
- Première livraison `001`, puis `002`, `003`, … jusqu’à `999` ; décider d’une
  nouvelle convention avant d’épuiser le compteur, sans retour à zéro.
- Chaque livraison du mod consomme le numéro suivant, correctifs compris.
  Aucun suffixe `.1`, `-hotfix` ou numéro lié à un chantier worldgen.
- Une modification documentaire seule n’incrémente pas les binaires.
- Une version publiée désigne un commit et des artefacts immuables. Ne pas
  renommer les tags alpha ni remplacer leurs pièces jointes.

| Emplacement | Valeur pour cette transition |
| --- | --- |
| `gradle.properties` → `mod_version` et `pack_version` | `beta.001` |
| `packwiz/pack.toml` → `version` | `beta.001` |
| Métadonnées Fabric du JAR, issues de Gradle | `beta.001` |
| Futur tag Git / Gitea, sans préfixe `v` | `beta.001` |
| JAR, convention Gradle `sanctuary-<version>.jar` | `sanctuary-beta.001.jar` |
| Export MRpack | `Sanctuary-beta.001.mrpack` |

`scripts/pack.py check`, également exécuté par `verifyPack`, refuse un format
différent ou un désalignement entre le mod et les manifestes du pack.
`scripts/publish_pack.py` utilise la version exacte pour les nouveaux tags.
Le canal packwiz et le chemin `mods/sanctuary.pw.toml` restent stables.

Ce nom est une version textuelle personnalisée, pas une version SemVer.
Fabric Loader 0.19.5 charge le mod avec sa valeur exacte, mais écrit un
avertissement `isn't compatible with Loader's extended semantic version format`.
Pour les futures dépendances à Sanctuary, ne pas supposer qu’une plage SemVer
compare ce compteur ; les GameTests actuels déclarent `"sanctuary": "*"` dans
leurs dépendances. Les mises à jour du pack suivent les manifestes et hashes
du canal packwiz.

## Génération, sauvegardes et suite

Ce compteur désigne une livraison, pas une version de génération ou de format
de sauvegarde. La première étape BETA-01 reprenait le code de jeu de l’alpha.30.7, notamment le
codec `sanctuary:island_v24`, sans modifier les identifiants `sanctuary:*`, les
journaux, les paramètres ou les chunks. Ce renommage n’impose pas à lui seul
un nouveau monde ; les contraintes des anciennes générations restent celles
de leurs notes de version. Aucune migration de sauvegarde n’est livrée ici.

Le créateur clôt le chantier worldgen sur ce socle. Le [backlog](backlog.md)
prévoit une passe courte sur les expansions, puis la progression en jeu.
Les systèmes de progression décrits dans la vision restent à implémenter.

## Validation et distribution

La transition est préparée localement. La publication des artefacts, l’avancement
du canal et la synchronisation de l’instance Prism suivent une demande de
livraison et la [procédure packwiz](packwiz.md). Aucune de ces opérations n’est
effectuée par le seul changement de version des sources.

Vérifications de la première étape BETA-01 sur macOS, Java 25, Minecraft 26.3-pre-2.
Elles précèdent les expéditions et la simplification finale du nom interne ;
les anciens logs gardent leur libellé temporaire :

- Les 13 cas de versionnement passent : compteurs admis, formats refusés et
  désalignements mod/pack/manifeste. Les scripts Python compilent.
- `./gradlew check build assemblePack` échoue après 6 min 56 s : **30 GameTests
  réussissent sur 32**. Les contrôles purs précédant les GameTests passent.
  `populationTerrainAndNaturalSpawnRemainPresent` attend encore une hauteur de
  384 blocs, alors que le monde courant mesure 640 blocs.
  `retainedHydrologySurvivesNativeDecoration` refuse le support naturel d’une
  cellule de sédiment en `x=-141, z=-86, bedY=238`, sur Moyen 724, graine `0`.
  Ces deux assertions figurent déjà dans l’alpha.30.7 ; aucune n’est corrigée
  ou désactivée dans les sources de BETA-01. Leur remise en cohérence reste ouverte.
- `./gradlew build assemblePack -x :sanctuary:check` réussit ensuite en 2 s,
  pour construire les artefacts séparément. Cette exclusion ponctuelle ne
  constitue pas une réussite du contrôle complet ci-dessus.
- Le JAR alpha.30.7 local correspond au SHA-256 publié dans le dépôt. La
  comparaison des archives montre **1 116 entrées strictement identiques** ;
  seul `fabric.mod.json` change, et seule sa valeur `version` diffère.
- Le packwiz assemblé et l’export MRpack sont vérifiés : version, dépendances
  exactes, index et empreintes, intégrité ZIP, un seul JAR Sanctuary.

Les reçus et logs restent ignorés dans `build/beta001-validation.json`,
`build/beta001-check-build-pack.log` et `build/beta001-assemble.log`.
Artefacts locaux : `mods/sanctuary/build/libs/sanctuary-beta.001.jar`
et `build/Sanctuary-beta.001.mrpack`. Aucun essai client graphique,
Windows ou rechargement de sauvegarde personnelle n’est revendiqué.

La simplification finale vers `beta.001` est également vérifiée : 12 cas
de format et d’alignement, construction et assemblage réussis, nom/version
du MRpack et version Fabric alignés. Comparé au JAR des expéditions ayant
passé les essais natifs, seul le champ `version` de `fabric.mod.json` change.
Le [reçu final des expéditions](expeditions-beta001.md#vérifications) remplace
les empreintes des artefacts de préparation.