pgr/docs/rules/200-GOVERNANCE.md

Governance rules

Scope

Ce document définit les règles communes de versioning et de lifecycle des releases gouvernées par PGR.

Les contrats détaillés des artefacts delta, history, handoff, manifest et prompt appartiennent à 210-WORKFLOW.md. Les règles de preuve et de gate appartiennent à 400-VALIDATION.md.

Principe de proportionnalité

La gouvernance MUST servir l'objectif du projet et MUST rester proportionnée au risque et à l'impact du changement.

Une règle, un contrôle ou une étape récurrente SHOULD exister lorsqu'il apporte une valeur identifiable, notamment pour :

• réduire les erreurs et régressions ;
• préserver une architecture ou un contrat ;
• rendre une décision explicite ;
• améliorer la sécurité ou la compatibilité ;
• faciliter maintenance, reprise ou diagnostic ;
• rendre une validation reproductible ;
• réduire le coût total du développement futur.

Une pratique qui ajoute principalement duplication, cérémonie ou coût de validation sans gain de preuve SHOULD être simplifiée, rendue optionnelle ou supprimée.

Version canonique de release

Chaque release unit gouvernée par PGR MUST avoir une version SemVer courante explicite.

Lorsqu'un dépôt utilise le fichier racine VERSION, ce fichier :

• MUST contenir exactement la version SemVer courante du release unit, sans préfixe v ;
• MUST contenir une seule ligne significative ;
• sert de repère simple entre l'état des sources, Git, les deltas et le lifecycle courant ;
• MUST NOT être interprété comme la version de tous les formats, schémas, documents, compteurs ou plateformes du projet.

Un manifeste technique MAY refléter exactement VERSION lorsque son propre contrat l'exige. Un autre mécanisme de versioning MAY rester indépendant lorsqu'il possède une sémantique différente, par exemple un versionCode Android, une révision de document ou une version de protocole.

PGR MUST NOT imposer une égalité globale entre tous les champs contenant un numéro de version.

Un champ de version qui n'est ni requis par l'écosystème ni utile au projet SHOULD être omis plutôt que maintenu comme duplication décorative.

Schéma SemVer PGR

Le lifecycle standard utilise les formes suivantes :

X.Y.Z-alpha.N
X.Y.Z-alpha.N.fix.M
X.Y.Z-beta.N
X.Y.Z-beta.N.fix.M
X.Y.Z-rc.N
X.Y.Z-rc.N.fix.M
X.Y.Z

N et M commencent à 1 et progressent de manière monotone dans leur scope.

Le préfixe Git d'une release stable est :

vX.Y.Z

rel.N MAY identifier une livraison ou un artefact de clôture, mais MUST NOT être traité comme une version produit SemVer.

Avant 1.0.0, PGR recommande la convention suivante lorsqu'elle correspond au projet :

• X = 0 indique que le contrat public durable n'est pas encore stabilisé ;
• Y identifie une série fonctionnelle ou architecturale ;
• Z identifie une release concrète de cette série ;
• 0.0.x MAY être utilisé pour une phase de fondation initiale.

Cette convention pré-1.0 complète SemVer sans modifier sa syntaxe.

Rôle des phases

Alpha

alpha porte le cadrage, l'implémentation et les changements de scope encore attendus dans la release.

alpha.1 MUST servir de gate de cadrage de la release. Avant une implémentation lourde, elle doit vérifier de manière proportionnée :

• la baseline et les règles applicables ;
• le plan ou la mission de la release ;
• la réalité du dépôt et des dépendances concernées ;
• les études ou décisions encore ouvertes ;
• les principaux risques et contraintes ;
• la stratégie de validation et les smokes nécessaires ;
• le dimensionnement des tranches ;
• lorsque la release possède un plan dédié, les responsabilités de clôture et de transition vers la suite ;
• l'état de l'horizon de roadmap et, lorsqu'il devient court ou incertain, le moment prévu pour le réexaminer.

Une tranche cible généralement un volume de travail cohérent et vérifiable. Une durée de l'ordre de 15 à 30 minutes MAY servir d'heuristique de découpage, mais MUST NOT être traitée comme une deadline ou un quota.

Beta

beta sert principalement à la stabilisation, l'intégration et la correction d'un scope fonctionnel déjà largement établi.

Une beta SHOULD NOT devenir une nouvelle phase d'expansion importante du scope sans REPLAN explicite.

Release candidate

rc représente un scope de release gelé sauf correction nécessaire à sa validation.

La RC MUST porter la gate complète applicable à la release candidate avant promotion stable. Un changement fonctionnel important découvert à ce stade SHOULD revenir vers une phase appropriée plutôt qu'être dissimulé dans une correction RC.

Stable

La promotion vers X.Y.Z SHOULD être proche d'une opération mécanique lorsque la RC correspondante a passé sa gate.

La promotion stable MUST néanmoins exécuter son propre gate proportionné pour vérifier les métadonnées, documents de release et artefacts réellement produits par cette promotion.

Le tag stable canonique est vX.Y.Z.

La vérification d'une publication ou d'une archive produite après le tag est une preuve distincte de la validation pré-tag.

Correctifs de tranche

Une forme .fix.M corrige uniquement la tranche immédiatement concernée.

Un fix :

• MUST conserver le scope fonctionnel de sa tranche ;
• MUST NOT introduire silencieusement une nouvelle fonctionnalité ou un nouveau chantier ;
• MAY corriger code, configuration, documentation, validation ou packaging nécessaires pour rendre la tranche conforme à son objectif ;
• remet son compteur M à 1 pour chaque nouvelle tranche.

L'arrivée à .fix.3 ou au-delà MUST déclencher une revue du plan et du diagnostic. Cette revue MAY conclure à la poursuite du fix, mais elle doit vérifier qu'un REPLAN n'est pas préférable.

REPLAN

REPLAN est un rôle de tranche alpha, pas un suffixe SemVer supplémentaire.

Un REPLAN est approprié lorsque le plan courant ne décrit plus correctement la réalité, par exemple après découverte d'une dépendance, d'un risque, d'une architecture ou d'un volume de travail significativement différent de l'hypothèse initiale.

Un REPLAN doit aboutir explicitement à l'un des résultats suivants :

CONTINUE
SPLIT
CONTINUE-NEXT-SESSION
ABANDON

Une interruption de conversation ou de session MUST NOT créer artificiellement une nouvelle version. Le même état de version et de tranche continue tant que le scope reste valable.

Une revue stratégique de versions futures MAY également se tenir dans une session séparée. Cette frontière de conversation n'est ni une release, ni une phase SemVer, ni une raison de modifier VERSION. Si la discussion produit une décision durable à matérialiser dans le dépôt, cette modification passe ensuite par une tranche gouvernée appropriée.

Abandon et supersession

Une version ou prerelease commencée n'est pas forcée vers stable uniquement pour préserver une séquence esthétique.

Lorsqu'un travail est abandonné ou superseded :

• l'état MUST être documenté ;
• la version déjà commencée est considérée comme consommée dans l'historique du projet ;
• les décisions, études et artefacts utiles SHOULD être conservés ;
• le contenu obsolète ou dangereux MAY être supprimé lorsque sa suppression et son remplacement sont explicitement justifiés.

Une nouvelle version MAY ensuite repartir d'une baseline saine sans prétendre que la version abandonnée n'a jamais existé.

Discipline de changement

Un changement de version, de phase ou de scope MUST être motivé par l'état réel du projet et non par la durée d'une conversation, le nombre de commits ou le désir de produire artificiellement une release.

PGR privilégie la traçabilité utile et la progression vers l'objectif du projet plutôt que la multiplication des versions, tests ou documents sans valeur opérationnelle.