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 et les versions fondatrices suivantes poursuivent le brainstorming, l'architecture, la nomenclature, le plan global et la préparation du prompt de 0.1.x.
• 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/<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 0.1.x.
• 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.