10 KiB
Validation rules
Scope
Ce document définit les règles communes de validation gouvernée par PGR : sélection des preuves, matrice de validation, catégories de contrôles, rôle des tests, audits et diagnostics, doubles de test, dépendances externes et autorité du gate opérateur.
La validation existe pour fournir une preuve utile proportionnée au changement. Elle MUST NOT devenir une répétition mécanique de toutes les commandes disponibles à chaque tranche.
Principe de validation proportionnée
Chaque tranche MUST sélectionner ses validations à partir de trois éléments :
scope modifié
↓
risques ou contrats potentiellement invalidés
↓
preuves nécessaires
Une modification documentaire locale SHOULD NOT déclencher un rebuild complet de toutes les plateformes sans raison. Inversement, une modification d'un contrat partagé, d'une dépendance transverse, de la toolchain ou d'une configuration globale MAY invalider plusieurs preuves antérieures et nécessiter une validation plus large.
Une preuve déjà acquise MAY être réutilisée tant qu'aucun changement pertinent ne l'a invalidée et qu'aucune gate globale de phase ne demande explicitement de la rejouer.
Les gates de beta, rc et promotion stable MAY élargir volontairement la validation pour démontrer l'intégration ou la cohérence de release.
Matrice de validation
Un projet suffisamment structuré SHOULD posséder une matrice de validation canonique, par défaut sous :
docs/validation/001-VALIDATION_MATRIX.md
La matrice décrit les contrôles disponibles et leur contexte d'utilisation. Elle ne constitue pas une obligation d'exécuter toutes les lignes à chaque changement.
Une entrée SHOULD identifier au minimum, lorsque pertinent :
- un identifiant stable ;
- une catégorie ;
- la commande ou le contrôle ;
- les prérequis ;
- le trigger ;
- la phase ou gate concernée ;
- le coût relatif ;
- l'acteur attendu, par exemple opérateur, CI ou revue.
La matrice est un document vivant. Elle MUST être mise à jour lorsqu'un contrôle canonique est ajouté, supprimé ou change réellement de responsabilité.
Catégories canoniques
PGR reconnaît les catégories suivantes :
FORMAT
AUDIT
CHECK
LINT
TEST-TARGETED
TEST-GLOBAL
DIAGNOSTIC
BUILD
PACKAGE
SMOKE
MAINTENANCE
PUBLISH
Elles décrivent la nature de la preuve, pas son importance absolue.
FORMAT
Vérifie une représentation ou un formatage déterministe sans modifier le contrat fonctionnel.
AUDIT
Vérifie une règle de dépôt, de structure, de dépendance, de documentation ou de gouvernance. Un audit automatisé PGR MUST être read-only et MUST NOT réparer le dépôt qu'il inspecte.
CHECK et LINT
CHECK valide la cohérence statique ou la compilation sans produire nécessairement un artefact livrable. LINT applique les diagnostics officiels ou spécialisés de qualité et de style lorsqu'ils sont pertinents.
TEST-TARGETED et TEST-GLOBAL
TEST-TARGETED prouve un comportement ou contrat dans le scope directement affecté. TEST-GLOBAL rejoue un ensemble plus large lorsque le changement ou la phase peut avoir invalidé plusieurs composants.
DIAGNOSTIC
Un diagnostic sert à comprendre un état, une performance ou un défaut. Il n'est pas automatiquement une gate PASS/FAIL. Lorsqu'un diagnostic devient un critère stable et objectivement vérifiable, il SHOULD être promu vers la catégorie de validation appropriée au lieu de rester une commande informelle obligatoire.
BUILD, PACKAGE et PUBLISH
Ces catégories restent distinctes : construire un artefact, l'empaqueter et le publier sont trois opérations différentes. Une réussite de build ne prouve pas automatiquement le packaging ou la publication.
SMOKE
Un smoke vérifie qu'un chemin d'utilisation ou d'intégration essentiel fonctionne dans un environnement ciblé. Il SHOULD rester court et centré sur la détection rapide d'une rupture majeure.
MAINTENANCE
Une opération de maintenance prépare ou nettoie l'environnement sans constituer en elle-même une preuve fonctionnelle, par exemple un clean explicitement requis.
Choix du mécanisme de preuve
Une propriété SHOULD être contrôlée au niveau le plus fiable et le moins redondant disponible :
compiler / language
↓
official linter or tool
↓
manifest / build system
↓
read-only structural audit
↓
behavior test
Un test MUST NOT parser le source uniquement pour vérifier une politique de dépôt lorsqu'un audit structurel est le mécanisme adapté.
Une règle architecturale qualitative qui nécessite du jugement humain MUST rester un point de revue plutôt qu'être transformée en regex fragile pour obtenir une automatisation artificielle.
Tests utiles et non redondants
Un test MUST apporter une preuve comportementale ou contractuelle utile. PGR MUST NOT imposer de tester chaque ligne, getter, setter ou branche triviale uniquement pour augmenter une métrique.
PGR MUST NOT imposer un pourcentage global minimal de code coverage. Le coverage MAY être utilisé comme diagnostic pour repérer des zones potentiellement sous-testées, mais il ne remplace pas l'analyse des contrats réellement importants.
Les scénarios équivalents SHOULD être regroupés ou paramétrés lorsque cela améliore la preuve et la lisibilité. Répéter de nombreuses variantes sans nouveau risque ou contrat couvert SHOULD être évité.
Les comportements critiques, erreurs significatives, frontières de contrat et cas limites pertinents SHOULD recevoir une validation proportionnée à leur risque.
Mocks, fakes, stubs et fixtures
Un double de test MAY être utilisé lorsqu'il permet d'isoler une dépendance externe, rendre un scénario déterministe ou provoquer proprement un comportement difficile à reproduire.
PGR n'impose pas une taxonomie de nommage rigide entre mock, fake, stub et fixture, mais le rôle du composant de test doit rester compréhensible.
Un mock réseau MAY prouver la logique qui dépend d'un contrat de transport. Il MUST NOT être présenté comme preuve que l'intégration réseau réelle fonctionne.
Lorsque plusieurs composants ont réellement besoin du même support de test, ce support MAY être mutualisé. Un composant commun de mocks ou fixtures SHOULD NOT être créé par anticipation s'il ne réduit pas une duplication réelle.
Le code de support de test SHOULD rester hors de l'API produit. La visibilité de production MUST NOT être élargie uniquement pour rendre un test plus facile à écrire lorsque l'écosystème fournit une séparation de test adaptée.
Réseau et dépendances externes
Un test unitaire SHOULD être indépendant d'Internet et des services externes non contrôlés.
Les validations utilisant réellement un réseau, un provider, une base externe, un device ou un service d'environnement doivent être reconnaissables comme integration, environment test ou smoke selon leur rôle.
Un test live MUST NOT être exécuté implicitement comme une unité déterministe si sa réussite dépend d'un service extérieur non contrôlé.
Lorsque cela est pertinent, les tests locaux SHOULD utiliser des ressources isolées telles que ports dynamiques, répertoires temporaires ou bases dédiées plutôt que des noms globaux arbitraires susceptibles d'entrer en collision.
Les ressources temporaires créées par une validation SHOULD être nettoyées avec les mécanismes naturels du langage ou du framework lorsque cela reste raisonnable.
Déterminisme
Les tests SHOULD éviter les dépendances implicites à l'ordre d'itération, au temps mur, au réseau réel, à des données locales ou à un hasard non contrôlé.
Lorsque le hasard fait partie du test, sa seed SHOULD être contrôlable ou enregistrable pour permettre la reproduction d'un échec.
Une attente fixe ou un sleep SHOULD NOT être utilisé comme mécanisme principal de synchronisation lorsque le système fournit une condition, un événement ou un timeout explicite plus fiable.
Autorité du gate opérateur
Une prévalidation par IA, script de génération ou revue statique MAY détecter des défauts avant livraison d'un delta, mais elle MUST NOT être présentée comme le résultat opérateur de la tranche.
Une tranche n'est PASS que lorsque la gate applicable a réellement été exécutée dans l'environnement autoritaire prévu par le projet.
Les statuts de validation reconnus sont :
PASS
FAIL
PARTIAL
BLOCKED
PASS signifie que les preuves requises par la tranche ont réussi.
FAIL signifie qu'au moins une preuve requise a échoué ou que le delta ne respecte pas son propre contrat.
PARTIAL signifie que seules certaines preuves ont pu être acquises et que le résultat ne doit pas être présenté comme un PASS complet.
BLOCKED signifie qu'un prérequis externe empêche actuellement d'exécuter une preuve requise sans conclure qu'elle aurait réussi ou échoué.
Le history MUST enregistrer le résultat réellement observé et les limitations pertinentes sans convertir artificiellement un résultat incomplet en PASS.
Transition après validation
Après un PASS, le history de la tranche est appliqué puis committé avant le delta suivant.
Après un FAIL, la correction reste normalement dans .fix.N du même niveau de maturité, sauf REPLAN, abandon ou supersession selon les règles de gouvernance.
Un résultat PARTIAL ou BLOCKED doit être résolu, explicitement accepté par un contrat de phase qui l'autorise, ou faire l'objet d'un replan ; il ne doit pas être silencieusement assimilé à un PASS.
Proportionnalité
Le but de PGR est d'augmenter la confiance tout en réduisant le coût total de développement et de maintenance.
Une validation qui consomme beaucoup de temps sans apporter de nouvelle preuve SHOULD être remise en question. À l'inverse, une validation coûteuse MAY être justifiée lorsqu'elle protège un contrat critique, une plateforme difficile à reproduire ou une frontière à fort impact.