khadhroony-solana-project/docs/rules/VERSION_WORKFLOW.md

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.
• VER-ID-015 — Pour une application Tauri KSP, workspace.package.version/la version Cargo résolue est la source de vérité de version du binaire et du bundle. tauri.conf.json omet donc son champ top-level version et laisse Tauri dériver la version depuis Cargo ; un bump du workspace ne provoque pas une modification artificielle de chaque tauri.conf.json.
• VER-ID-016 — Le package.json d'une application Tauri KSP est un manifeste frontend privé de dépendances et de scripts, pas une source de vérité de la release KSP. Sa propriété version, lorsqu'elle est conservée, n'est pas synchronisée automatiquement avec workspace.package.version et aucun canari KSP ne doit exiger leur égalité. Les gates de release desktop utilisent la version Cargo/Tauri dérivée et les métadonnées de bundle produites par cargo tauri build.

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/<X.Y.Z>/.
• VER-DELTA-003 — Une prerelease est tracée par deltas/<X.Y.Z>/pre.NNN.md et son correctif par deltas/<X.Y.Z>/pre.NNN-fix.NNN.md.
• VER-DELTA-004 — Une livraison de release finale est tracée par deltas/<X.Y.Z>/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-<delivery-id>.zip.
• VER-ARCHIVE-002 — Une livraison limitée à docs/ et/ou aux prompts se nomme ksp-doc-<delivery-id>.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/<X.Y.Z>/<delta-name>.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 avant rel.NNN est une tranche de préparation de publication minimale. Hors Cargo.toml et delta obligatoires, elle ne modifie que le prompt de démarrage de la release suivante, CHANGELOG.md et ROADMAP.md.

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

• VER-LIFECYCLE-006 — La prerelease immédiatement antérieure à la dernière prerelease de publication est dédiée à la réconciliation documentaire finale : plan, validation, README, USAGE et autres documents durables concernés. Elle ne finalise pas CHANGELOG.md, ROADMAP.md ni le prompt de la release suivante.

• VER-LIFECYCLE-007 — Lorsqu'un smoke final, un test live ou un gate réseau/provider est requis, une prerelease technique dédiée précède la prerelease de réconciliation documentaire. Cette tranche peut également porter les graphes et contrôles techniques finaux directement liés au gate, mais elle ne mélange pas la réconciliation README/USAGE ni la préparation de publication.

• VER-LIFECYCLE-008 — Lorsqu'aucun smoke/gate live final n'est pertinent, la tranche technique dédiée peut être omise ; les deux dernières responsabilités restent obligatoirement séparées entre réconciliation documentaire puis préparation de publication.

• VER-LIFECYCLE-009 — Un correctif pre.NNN-fix.MMM reste strictement dans le périmètre de responsabilité de pre.NNN. Un fix de smoke ne corrige pas README/USAGE/CHANGELOG/prompt ; un fix documentaire ne contient pas de nouveau smoke/runtime ; un fix de publication ne contient pas de correction documentaire durable hors CHANGELOG.md, ROADMAP.md et prompt suivant.

• VER-LIFECYCLE-010 — Si une anomalie appartenant à un couloir antérieur est découverte après son franchissement, elle ouvre une nouvelle prerelease dédiée à cette responsabilité au lieu d'être mélangée au fix de la tranche courante. Les couloirs postérieurs sont ensuite rejoués si nécessaire afin que la dernière prerelease reste une préparation de publication minimale.

• VER-LIFECYCLE-011 — Le plan établi en pre.001 réserve explicitement, dans sa prévision souple, le gate technique/live éventuel, la réconciliation documentaire et la préparation de publication. La numérotation peut évoluer, mais l'ordre de ces responsabilités ne doit pas être fusionné pour raccourcir artificiellement la release.

• VER-LIFECYCLE-012 — Une livraison rel.NNN effectue la mécanique de publication stable et ne sert pas de tranche de rattrapage. Tout nouveau défaut fonctionnel, test live manquant, correction README/USAGE/validation, ou préparation CHANGELOG/ROADMAP/prompt non achevée renvoie vers une prerelease appropriée avant rel.NNN.