# Versionnement, sessions et livraisons ## Portée Les règles `VER-*` définissent la progression des versions KSP, les identifiants de livraison, les deltas et la norme de travail par session. ## Versions du projet - **VER-PROJECT-001** — `0.0.x` est la phase fondatrice : dépôt, squelette, règles, architecture, planification et préparation de la première phase fonctionnelle. - **VER-PROJECT-002** — `0.0.1` contient uniquement le `.gitignore` initial. - **VER-PROJECT-003** — `0.0.2` installe le squelette minimal, les règles initiales, `README.md`, `Cargo.toml`, `rustfmt.toml` et `clippy.toml`, sans développement métier. - **VER-PROJECT-004** — `0.0.3` clôt la phase fondatrice avec l'architecture, la nomenclature, le plan global et le prompt de la première release fonctionnelle concrète. - **VER-PROJECT-005** — `0.1.x` ouvre la première phase de développement fonctionnel seulement après clôture de la session fondatrice. ## Version Cargo et identifiant de livraison - **VER-ID-001** — Les versions Cargo respectent strictement SemVer et utilisent des identifiants numériques sans zéro initial, par exemple `0.0.2-pre.1`. - **VER-ID-002** — Une livraison de prerelease utilise l'identifiant `X.Y.Z-pre.NNN`, par exemple `0.0.2-pre.001`. - **VER-ID-003** — Un correctif d'une prerelease utilise `X.Y.Z-pre.NNN-fix.NNN` ; la numérotation `fix.NNN` recommence à `001` pour chaque nouvelle prerelease. - **VER-ID-004** — Une livraison correspondant à la publication d'une release finale utilise l'identifiant de livraison `X.Y.Z-rel.NNN`. Le marqueur `rel` appartient au système de livraison/delta et non à la version Cargo finale. - **VER-ID-005** — Pour une release finale, `workspace.package.version` utilise la version SemVer finale `X.Y.Z`, sans suffixe `rel`, car une version Cargo `X.Y.Z-rel.N` serait elle-même une prerelease SemVer et non la release finale. - **VER-ID-006** — Un nouveau numéro de prerelease correspond à une nouvelle tranche planifiée ; un correctif corrige la tranche existante sans en redéfinir le périmètre fonctionnel principal. - **VER-ID-007** — Lorsqu'un correctif modifie au moins un fichier participant au code, au build, au runtime, à la configuration exécutable ou à une migration de données, `workspace.package.version` dans le `Cargo.toml` racine est synchronisé avec l'identifiant technique du delta. Cela couvre notamment les sources `.rs`, `.ts`, les ressources `.html` utilisées au runtime, les fichiers `.toml` de projet/configuration, les migrations SQL et tout autre artefact effectivement consommé par le système. - **VER-ID-008** — Un correctif limité à de la documentation ou à des fichiers externes/de référence non consommés par le build ou le runtime ne modifie pas `workspace.package.version`. Le décalage entre l'identifiant du delta et la version Cargo indique alors volontairement qu'aucun changement de code/runtime n'a eu lieu. - **VER-ID-009** — Toute publication non-fix d'une prerelease ou d'une release synchronise `workspace.package.version` avec la version correspondante, même lorsque la dernière tranche de travail ne contient que de la documentation. - **VER-ID-010** — La représentation Cargo d'un correctif de prerelease conserve l'ordre SemVer avec des identifiants séparés par des points : la livraison `0.0.2-pre.001-fix.003` correspond à la version Cargo `0.0.2-pre.1.fix.3`. - **VER-ID-011** — Les crates qui héritent `version.workspace = true` ne redéfinissent pas localement cette version. - **VER-ID-012** — Avant `0.1.x`, les prereleases et releases sont les points de commit normaux ; les correctifs intermédiaires peuvent rester des livraisons d'échange non commitées. - **VER-ID-013** — À partir de `0.1.x`, chaque delta est commité, y compris lorsqu'il contient un état imparfait qui sera corrigé par un delta `fix` ultérieur. L'historique Git doit conserver la séquence réelle des travaux et corrections. - **VER-ID-014** — Une livraison `rel.NNN` peut être corrigée avant la publication stable par `rel.NNN-fix.NNN` ou remplacée par une nouvelle livraison `rel.NNN` selon le besoin. Une release déjà considérée comme stable et taguée `vX.Y.Z` n'est normalement pas réécrite ; une correction fonctionnelle ultérieure ouvre une nouvelle version appropriée. ## Git - **VER-GIT-001** — Les commits correspondant aux livraisons utilisent un libellé versionné de forme `vX.Y.Z-pre.NNN`, `vX.Y.Z-pre.NNN-fix.NNN`, `vX.Y.Z-rel.NNN` ou, si nécessaire avant publication stable, `vX.Y.Z-rel.NNN-fix.NNN`. - **VER-GIT-002** — Les prereleases, fixes et livraisons `rel` n'ont pas besoin d'un tag Git dédié. - **VER-GIT-003** — Le dernier commit validé comme release stable reçoit le tag Git `vX.Y.Z`. - **VER-GIT-004** — La suppression technique d'un tag créé prématurément ne supprime pas le commit visé ; néanmoins une release déjà publiée comme stable ne doit normalement pas être réécrite. ## Deltas - **VER-DELTA-001** — Il existe un seul arbre `deltas/` pour tout le dépôt, indépendamment du type de fichiers modifiés. - **VER-DELTA-002** — Les deltas sont regroupés sous la version cible : `deltas//`. - **VER-DELTA-003** — Une prerelease est tracée par `deltas//pre.NNN.md` et son correctif par `deltas//pre.NNN-fix.NNN.md`. - **VER-DELTA-004** — Une livraison de release finale est tracée par `deltas//rel.NNN.md`. - **VER-DELTA-005** — Un delta indique au minimum : base requise, objectif, fichiers ajoutés, fichiers modifiés, fichiers supprimés, validations exécutées, validations non exécutées, décisions prises et questions ouvertes. - **VER-DELTA-006** — Une suppression est explicitement listée ; l'extraction d'une archive ne constitue jamais une suppression implicite. - **VER-DELTA-007** — Une livraison publiée n'est jamais remplacée silencieusement sous le même identifiant. ## Archives d'échange - **VER-ARCHIVE-001** — Une livraison pouvant toucher la racine, le code et/ou la documentation se nomme `ksp-general-.zip`. - **VER-ARCHIVE-002** — Une livraison limitée à `docs/` et/ou aux prompts se nomme `ksp-doc-.zip`. - **VER-ARCHIVE-003** — Le type `general` ou `doc` ne crée aucun versionnement parallèle ; les deux utilisent le même identifiant et le même répertoire `deltas/`. - **VER-ARCHIVE-004** — L'archive contient uniquement les fichiers ajoutés ou modifiés par la livraison, plus son fichier `deltas//.md`. - **VER-ARCHIVE-005** — Les lockfiles, caches, secrets, sorties de compilation et autres artefacts explicitement ignorés ne sont pas livrés. ## Norme de session - **VER-SESSION-001** — Toute nouvelle session fonctionnelle commence par une phase de brainstorming puis une phase de planification avant toute modification de développement. - **VER-SESSION-002** — Après validation du plan, la session peut enchaîner développement, validations/tests, documentation finale puis préparation du prompt de la session suivante. - **VER-SESSION-003** — La session fondatrice actuelle remplace la phase de développement par la définition des règles, de l'architecture, du squelette et du plan nécessaires à KSP. - **VER-SESSION-004** — La session fondatrice doit se terminer avec un workspace initial cohérent, la documentation/règles nécessaires, un plan de poursuite et un prompt permettant d'ouvrir la première release fonctionnelle ; pour la fondation actuelle, il s'agit de `0.1.1`. - **VER-SESSION-005** — Le changelog général, lorsqu'il existe, est synchronisé en fin de session à partir des deltas validés et ne remplace pas les deltas détaillés. ## Première et dernière prerelease d'une phase de développement - **VER-LIFECYCLE-001** — La première prerelease d'une nouvelle phase fonctionnelle est prioritairement consacrée au brainstorming, à l'inventaire, aux risques, dépendances, hors-périmètre, critères de validation et plan de travail. - **VER-LIFECYCLE-002** — Une phase importante ne commence pas directement par des modifications fonctionnelles dispersées sans cadrage. - **VER-LIFECYCLE-003** — La dernière prerelease d'une phase est prioritairement consacrée aux validations finales, écarts résiduels, documentation finale, synthèse changelog et prompt de reprise. - **VER-LIFECYCLE-004** — Le document de planification établi ou révisé pendant `pre.001` d'une version détaille une prévision souple des prereleases de cette version : objectifs de chaque tranche, ordre envisagé, dépendances, validations et éventuels hors-périmètre. Cette prévision peut être réorganisée lorsque la réflexion ou le développement le justifie ; le delta trace ces changements. - **VER-LIFECYCLE-005** — Le `ROADMAP.md` n'est pas obligé de reprendre une entrée par prerelease. Il décrit la trajectoire globale ; le plan de version porte le découpage prévisionnel plus fin des prereleases.