Sasedev/pgr
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

0.0.1-alpha.5

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-09-23 08:13:06 +02:00
parent 797230bc33
commit 1aa4c0e0b7
7 changed files with 405 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
docs/rules/000-README.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/rules/000-README.md -->
<!-- version: 4 -->
<!-- version: 5 -->
# Index des règles PGR
@@ -12,6 +12,7 @@ Les règles détaillées de Project Governance Rules sont organisées ici progre
- [`200-GOVERNANCE.md`](200-GOVERNANCE.md) — versioning, lifecycle des releases, fixes, cadrage, replan et abandon/supersession.
- [`210-WORKFLOW.md`](210-WORKFLOW.md) — contrats des artefacts workflow, ordre delta/history/commit, reprise et baselines de release.
- [`300-DOCUMENTATION.md`](300-DOCUMENTATION.md) — rôles des documents, taxonomie, révisions internes, documents vivants et snapshots historiques.
- [`400-VALIDATION.md`](400-VALIDATION.md) — matrice de validation, preuves proportionnelles, tests/audits/diagnostics, doubles de test et autorité du gate opérateur.
## Organisation prévue

205
docs/rules/400-VALIDATION.md Normal file
View File

@@ -0,0 +1,205 @@
<!-- file: docs/rules/400-VALIDATION.md -->
<!-- version: 1 -->
# 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 :
```text
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 :
```text
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 :
```text
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 :
```text
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 :
```text
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.

50
docs/validation/001-VALIDATION_MATRIX.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/validation/001-VALIDATION_MATRIX.md -->
<!-- version: 2 -->
<!-- version: 3 -->
# Matrice de validation PGR
@@ -7,18 +7,21 @@
Cette matrice décrit les validations canoniques du dépôt PGR. Elle évolue avec le projet et ne doit pas inventer des scripts uniquement pour remplir une case.
PGR est encore dans sa phase de bootstrap documentaire. Les contrôles initiaux restent donc volontairement simples et reposent sur Git, des commandes shell ciblées et une revue opérateur explicite.
La matrice définit les contrôles disponibles ; chaque delta sélectionne uniquement ceux qui sont nécessaires pour son scope et les preuves qu'il peut avoir invalidées.
## Commandes initiales
Les catégories et règles de sélection sont définies dans [`../rules/400-VALIDATION.md`](../rules/400-VALIDATION.md).
| ID | Catégorie | Commande / contrôle | Trigger | Phase |
|-------------------------|-----------|------------------------------------------------------------------------------------------|--------------------------------------------|----------------------|
| `PGR-GIT-001` | CHECK | `git diff --check` ou `git diff --cached --check` selon l'état de l'index | toute modification suivie par Git | alpha/beta/RC/stable |
| `PGR-GIT-BOOTSTRAP-001` | CHECK | `git add .` puis `git diff --cached --check` | bootstrap ou fichiers entièrement nouveaux | bootstrap |
| `PGR-VERSION-001` | CHECK | comparer `VERSION` à la version attendue par le delta courant | changement de tranche/version | alpha/beta/RC/stable |
| `PGR-LAYOUT-001` | REVIEW | `find . -type f -not -path './.git/*' -print` puis comparaison au scope du delta | ajout/suppression/déplacement de fichiers | alpha/beta/RC/stable |
| `PGR-DOC-001` | REVIEW | vérifier headers `file/version`, chemins, liens et responsabilités des documents touchés | modification documentaire | alpha/beta/RC/stable |
| `PGR-STATUS-001` | CHECK | `git status --short` | avant fermeture d'une tranche | alpha/beta/RC/stable |
## Contrôles actifs
| ID | Catégorie | Commande / contrôle | Prérequis | Trigger | Phase | Coût | Acteur |
|-------------------|-----------|------------------------------------------------------------------------------------------|------------------------|-------------------------------|----------------------|--------|-----------------|
| `PGR-GIT-001` | `CHECK` | `git diff --check` ou `git diff --cached --check` selon l'état de l'index | Git | toute modification suivie | alpha/beta/RC/stable | faible | opérateur |
| `PGR-VERSION-001` | `CHECK` | comparer `VERSION` à la version attendue par le delta courant | fichier `VERSION` | changement de tranche/version | alpha/beta/RC/stable | faible | opérateur |
| `PGR-LAYOUT-001` | `AUDIT` | comparer les fichiers ajoutés/remplacés/supprimés au scope déclaré du delta | scope du delta | changement de structure | alpha/beta/RC/stable | faible | opérateur/revue |
| `PGR-DOC-001` | `AUDIT` | vérifier headers `file/version`, chemins, liens et responsabilités des documents touchés | fichiers documentaires | modification documentaire | alpha/beta/RC/stable | faible | opérateur/revue |
| `PGR-STATUS-001` | `CHECK` | `git status --short` | Git | avant fermeture d'une tranche | alpha/beta/RC/stable | faible | opérateur |
Un contrôle manuel peut rester dans la matrice lorsqu'aucun audit automatisé fiable n'existe encore. PGR SHOULD automatiser uniquement les propriétés stables et objectivement contrôlables.
## Politique Eclipse actuelle
@@ -37,16 +40,16 @@ Le `.gitignore` doit donc contenir :
!.settings/org.eclipse.core.resources.prefs
```
## Gate documentaire de bootstrap
## Gate documentaire courante
Pour une tranche documentaire de bootstrap, le delta doit sélectionner uniquement les contrôles nécessaires à son scope. Une gate typique peut inclure :
Pour une tranche documentaire, le delta sélectionne les contrôles nécessaires à son scope. Une gate typique peut inclure :
```bash
git status --short
test "$(cat VERSION)" = "<version attendue>"
find . -type f -not -path './.git/*' -print
git diff --check
git add <fichiers du delta>
git diff --cached --check
@@ -55,18 +58,19 @@ git status --short
Le placeholder `<version attendue>` appartient à la documentation de la matrice ; chaque delta fournit la commande concrète avec sa propre version.
L'opérateur vérifie également, selon le scope du delta, que :
Selon le scope, la gate peut également vérifier que :
- aucun répertoire vide n'a été ajouté uniquement pour anticiper le futur ;
- les fichiers ajoutés/remplacés/supprimés correspondent au delta ;
- les headers `file/version` correspondent aux chemins réels ;
- `VERSION` contient exactement une ligne avec la version de la tranche courante ;
- les liens Markdown de navigation principaux sont cohérents ;
- les liens Markdown principaux sont cohérents ;
- aucun secret, chemin machine absolu ou artefact local non autorisé n'est introduit ;
- les exceptions Git intentionnellement versionnées restent effectivement traçables.
- les exceptions Git intentionnellement versionnées restent effectivement traçables ;
- aucun répertoire ou contrôle n'est ajouté uniquement pour satisfaire une structure théorique.
## Autorité de validation
Une validation n'est `PASS` qu'après exécution réelle du gate opérateur. La génération du delta ou une prévalidation par l'IA ne constitue pas le résultat opérateur.
Une validation n'est `PASS` qu'après exécution réelle de la gate opérateur applicable. La génération du delta ou une prévalidation par l'IA ne constitue pas le résultat opérateur.
Après un `PASS`, l'historique de la tranche validée est fourni séparément du delta suivant. Un `FAIL` reste dans le scope de la tranche courante via `.fix.N`, sauf REPLAN ou abandon explicitement justifié.
Les résultats `FAIL`, `PARTIAL` et `BLOCKED` doivent être enregistrés comme tels et ne doivent pas être transformés implicitement en PASS.
Après un `PASS`, l'history de la tranche validée est fourni séparément du delta suivant. Un `FAIL` reste normalement dans le scope de la tranche courante via `.fix.N`, sauf REPLAN, abandon ou supersession explicitement justifié.