83 lines
11 KiB
Markdown
83 lines
11 KiB
Markdown
<!-- file: docs/rules/VERSION_WORKFLOW.md -->
|
|
<!-- version: 7 -->
|
|
|
|
# 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/<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`.
|