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

0.0.1-alpha.4

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-09-23 07:50:55 +02:00
parent 6bbadb57ee
commit cbb842bb3a
6 changed files with 381 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
RULES.md
View File

@@ -1,5 +1,5 @@
<!-- file: RULES.md -->
<!-- version: 3 -->
<!-- version: 4 -->
# Index normatif Project Governance Rules
@@ -76,6 +76,7 @@ Famille actuellement active :
- [`docs/rules/200-GOVERNANCE.md`](docs/rules/200-GOVERNANCE.md) — versioning, lifecycle des releases, fixes, cadrage, replan et abandon/supersession.
- [`docs/rules/210-WORKFLOW.md`](docs/rules/210-WORKFLOW.md) — plans, deltas, histories, prompts, handoffs, manifests, commits, baselines et reprise de session.
- [`docs/rules/300-DOCUMENTATION.md`](docs/rules/300-DOCUMENTATION.md) — rôles documentaires, taxonomie, révisions internes, documents vivants et conservation historique.
Une famille de règles n'est créée que lorsqu'elle possède un contenu réel ; aucun répertoire vide n'est requis pour anticiper une future technologie.

2
VERSION
View File

@@ -1 +1 @@
0.0.1-alpha.3
0.0.1-alpha.4

90
deltas/0.0.1/alpha.4.md Normal file
View File

@@ -0,0 +1,90 @@
<!-- file: deltas/0.0.1/alpha.4.md -->
<!-- version: 1 -->
# Delta 0.0.1-alpha.4 — documentation governance
## Baseline
Version attendue avant application :
```text
0.0.1-alpha.3
```
Le history `history/0.0.1/alpha.3.md` MUST avoir été appliqué et committé avant ce delta.
Version après application :
```text
0.0.1-alpha.4
```
## Objet
Formaliser la gouvernance documentaire commune sans transformer la documentation en activité cérémonielle : responsabilités des documents, taxonomie, révisions internes, distinction vivant/historique et conservation proportionnée.
## Scope
REPLACE :
```text
VERSION
RULES.md
docs/rules/000-README.md
```
ADD :
```text
docs/rules/300-DOCUMENTATION.md
deltas/0.0.1/alpha.4.md
```
DELETE : aucun.
## Changements
- `VERSION` passe à `0.0.1-alpha.4` ;
- les rôles de `README.md`, `000-README.md`, `USAGE.md`, `RULES.md`, `ROADMAP.md`, `CHANGELOG.md` et des objectifs sont séparés ;
- une taxonomie documentaire commune est définie sans imposer de répertoires vides ;
- idées, études et décisions sont distinguées ;
- documents vivants et snapshots historiques ont des règles différentes ;
- les headers `file` / `version` sont définis comme révisions internes indépendantes de SemVer ;
- le déplacement d'un fichier met à jour son chemin et sa révision ;
- les formats stricts restent exempts de header artificiel ;
- la conservation historique est utile mais non infinie ;
- la politique linguistique de PGR interdit les sous-arbres de traduction dans le dépôt principal ;
- la documentation doit rester proportionnée et non cérémonielle.
## Validation opérateur
```bash
test "$(cat VERSION)" = "0.0.1-alpha.4"
test -f docs/rules/300-DOCUMENTATION.md
grep -Fx '<!-- file: docs/rules/300-DOCUMENTATION.md -->' docs/rules/300-DOCUMENTATION.md
grep -F "`USAGE.md` est un guide d'utilisation durable" docs/rules/300-DOCUMENTATION.md
grep -F '`ROADMAP.md` décrit la trajectoire macro du projet' docs/rules/300-DOCUMENTATION.md
grep -F '`version` est une révision interne du fichier. Elle est indépendante de `VERSION`' docs/rules/300-DOCUMENTATION.md
grep -F 'Un snapshot historique MUST NOT être réécrit silencieusement' docs/rules/300-DOCUMENTATION.md
grep -F "PGR MUST NOT créer d'arborescence `fr/`, `en/`, `de/`" docs/rules/300-DOCUMENTATION.md
grep -F 'La documentation est une aide au développement et à la maintenance, pas une fin en soi.' docs/rules/300-DOCUMENTATION.md
git diff --check
git add VERSION RULES.md docs/rules/000-README.md docs/rules/300-DOCUMENTATION.md \
deltas/0.0.1/alpha.4.md
git diff --cached --check
git status --short
```
La revue opérateur vérifie également que cette tranche ne crée aucun répertoire documentaire vide et ne mélange pas encore les règles détaillées de validation prévues pour `alpha.5`.
## Transition
PASS : enregistrer `history/0.0.1/alpha.4.md`, committer `alpha.4`, puis passer à `0.0.1-alpha.5`.
FAIL : rester dans `alpha.4` avec `alpha.4.fix.1`, sauf REPLAN si le défaut remet en cause le scope ou le plan.

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

@@ -1,5 +1,5 @@
<!-- file: docs/rules/000-README.md -->
<!-- version: 3 -->
<!-- version: 4 -->
# Index des règles PGR
@@ -11,6 +11,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.
## Organisation prévue

211
docs/rules/300-DOCUMENTATION.md Normal file
View File

@@ -0,0 +1,211 @@
<!-- file: docs/rules/300-DOCUMENTATION.md -->
<!-- version: 1 -->
# Documentation rules
## Scope
Ce document définit les règles communes de documentation gouvernée par PGR : rôle des documents, taxonomie, révision interne des fichiers, distinction entre documents vivants et snapshots historiques, conservation et suppression.
La documentation doit réduire le coût de compréhension et de reprise du projet. Elle MUST NOT devenir une duplication systématique du code, des manifests ou de l'historique de release.
## Responsabilités documentaires
Chaque type de document doit conserver une responsabilité claire.
### Root `README.md`
Le `README.md` racine présente le projet et fournit l'onboarding et la navigation de premier niveau.
Il SHOULD rester concis et pointer vers les documents spécialisés plutôt que recopier leurs contenus.
### `docs/000-README.md`
`docs/000-README.md` est l'index principal de la collection documentaire lorsqu'un projet possède une documentation structurée sous `docs/`.
Il décrit l'organisation documentaire et les points d'entrée utiles ; il MUST NOT devenir un second README produit ou un journal de release.
Un sous-ensemble documentaire MAY utiliser son propre `000-README.md` lorsqu'un index local améliore réellement la navigation.
### README local
Un `README.md` local à un composant, module ou répertoire décrit la responsabilité et les informations d'entrée propres à ce composant.
Il SHOULD NOT recopier la documentation globale qui reste mieux possédée ailleurs.
### `USAGE.md`
Lorsqu'il existe, `USAGE.md` est un guide d'utilisation durable et autant que possible indépendant d'une version précise.
Il peut contenir exemples, scénarios, contraintes opérationnelles et contrats d'utilisation. Il MUST NOT servir de changelog, de preuve de validation, de résumé de prerelease ou de history de tranche.
### `RULES.md`
`RULES.md` est le point d'entrée normatif du projet. Il présente la hiérarchie et les règles fondamentales et renvoie vers les familles détaillées lorsque celles-ci existent.
Il SHOULD NOT devenir un fichier monolithique contenant toutes les règles spécialisées.
### `ROADMAP.md`
`ROADMAP.md` décrit la trajectoire macro du projet : objectifs de versions, grandes étapes et ordre fonctionnel attendu.
Il MUST NOT devenir un journal des prereleases ou recopier les histories de tranche.
Lorsqu'un projet utilise des statuts de roadmap, la convention PGR est :
```text
( ) planned
(x) completed
(d) deferred
(c) cancelled
```
Une autre convention MAY être adoptée par un projet si elle est explicitement définie et cohérente.
### `CHANGELOG.md`
`CHANGELOG.md` décrit les changements utiles aux utilisateurs ou intégrateurs d'une release.
Par défaut, les tranches `alpha` et `beta` ne doivent pas créer de bruit de changelog simplement parce qu'elles existent. Une RC MAY préparer l'entrée de release et la stable la finalise.
Un projet MAY documenter des prereleases publiquement distribuées lorsque cela apporte une information réelle aux consommateurs.
### Objectifs
Un document sous `docs/objectives/` décrit la mission durable, les objectifs, contraintes et non-objectifs du projet.
Il MUST NOT être remplacé par `ROADMAP.md` : les objectifs expliquent pourquoi le projet existe et ce qu'il cherche à garantir ; la roadmap décrit comment sa trajectoire est découpée.
## Taxonomie documentaire
La taxonomie doit rester sémantique et proportionnée. Les familles communes comprennent notamment :
```text
docs/rules/
docs/objectives/
docs/ideas/
docs/studies/
docs/architecture/
docs/plans/
docs/validation/
docs/development/
docs/testing/
docs/operations/
docs/reference/
docs/formats/
```
Ces répertoires ne sont créés que lorsqu'ils possèdent un contenu réel.
Un répertoire générique tel que `misc/` SHOULD NOT devenir la destination par défaut des documents dont la responsabilité n'a pas été déterminée.
Une technologie ou un projet MAY introduire des familles supplémentaires lorsqu'elles représentent une responsabilité documentaire stable.
## Idées, études et décisions
Une idée est une possibilité non engagée. Elle ne doit pas être présentée comme une décision ou une promesse de roadmap.
Une étude existe lorsqu'un choix réel doit être comparé ou démontré. Elle SHOULD expliciter la question, les contraintes, les options pertinentes, les observations et la décision ou conclusion lorsqu'elle existe.
Si une décision est déjà imposée par une contrainte explicite et qu'aucune alternative réelle n'est ouverte, une étude artificielle SHOULD NOT être créée uniquement pour respecter un processus.
Les décisions durables doivent ensuite être reflétées dans l'architecture, les règles, objectifs ou autres documents vivants qui possèdent réellement ce contrat.
## Documents vivants et snapshots historiques
PGR distingue :
```text
living document
→ décrit l'état ou le contrat courant et évolue lorsque cet état change réellement
historical snapshot
→ enregistre un état, une décision ou une preuve à un instant donné
```
Exemples de documents généralement vivants :
```text
README.md
RULES.md
ROADMAP.md
docs/000-README.md
PROJECT_PROFILE
validation matrix
architecture courante
```
Exemples de snapshots généralement historiques après livraison/commit :
```text
delta
history
handoff livré
étude conclue conservée comme preuve
release/publish record
```
Un snapshot historique MUST NOT être réécrit silencieusement pour correspondre à l'état courant. Une correction factuelle importante doit être explicite et préserver la traçabilité utile.
Un document vivant SHOULD être mis à jour lorsqu'un changement rend son contenu réellement obsolète ; il ne doit pas être modifié à chaque tranche uniquement pour créer une trace d'activité.
## Header `file` / `version`
Pour les formats texte qui acceptent naturellement des commentaires, PGR SHOULD utiliser un header interne de la forme :
```text
file: relative/path
version: N
```
La syntaxe de commentaire dépend du format. Pour Markdown :
```html
<!-- file: docs/example.md -->
<!-- version: 1 -->
```
`file` identifie le chemin relatif canonique du fichier.
`version` est une révision interne du fichier. Elle est indépendante de `VERSION`, de SemVer produit, des versions de protocole, de schema ou de package.
La révision interne MUST être incrémentée lorsqu'un fichier subit une modification réelle gouvernée ou un déplacement qui modifie son chemin canonique. Elle SHOULD NOT être incrémentée pour une opération de formatage strictement mécanique qui ne modifie aucun contenu gouverné.
Lors d'un déplacement, le header `file` MUST être mis à jour vers le nouveau chemin.
Les formats stricts ou formats dans lesquels un tel header serait invalide MUST NOT recevoir de champ artificiel uniquement pour satisfaire cette convention. La provenance ou révision est alors portée ailleurs si nécessaire.
## Noms et ordre documentaire
Les noms de fichiers doivent refléter leur responsabilité. Les suffixes vagues ou chronologiques tels que `new`, `old`, `final2` SHOULD NOT être utilisés comme mécanisme de versionnement.
Un préfixe numérique MAY être utilisé pour stabiliser la navigation d'une collection documentaire lorsqu'un ordre est utile. Le numéro organise la lecture ; il ne constitue pas un identifiant normatif de règle.
## Conservation, suppression et remplacement
Une documentation historique utile SHOULD être conservée lorsqu'elle explique une décision, une migration ou permet une reprise fiable.
Un document MAY être supprimé lorsqu'il est devenu nuisible, réellement obsolète, redondant ou explicitement superseded. Lorsque la suppression n'est pas évidente, le changement SHOULD identifier la raison et le remplacement éventuel.
PGR MUST NOT imposer la conservation infinie de contenu sans valeur de preuve ou de reprise.
## Langues et traductions
Le choix de langue appartient au projet et doit rester cohérent avec ses règles locales.
Pour PGR lui-même, la nomenclature technique, les chemins, identifiants et le code restent en anglais tandis que les explications normatives sont en français.
PGR MUST NOT créer d'arborescence `fr/`, `en/`, `de/` ou équivalente dans son dépôt principal. Une traduction intégrale éventuelle appartient à un dépôt distinct tel que `pgr-en`, `pgr-de` ou `pgr-ar`.
## Documentation proportionnée
Un document SHOULD exister lorsqu'il possède une responsabilité durable, une décision, une preuve ou une information de reprise qui ne serait pas mieux portée ailleurs.
PGR MUST NOT imposer :
- un document vide pour satisfaire une structure théorique ;
- une copie de la même information dans plusieurs fichiers sans propriétaire clair ;
- un document de décision lorsqu'aucune décision n'est réellement ouverte ;
- une mise à jour documentaire purement cérémonielle à chaque tranche.
La documentation est une aide au développement et à la maintenance, pas une fin en soi.

75
history/0.0.1/alpha.4.md Normal file
View File

@@ -0,0 +1,75 @@
<!-- file: history/0.0.1/alpha.4.md -->
<!-- version: 1 -->
# History 0.0.1-alpha.4 — documentation governance
## Statut
FAIL
Le contenu documentaire de la tranche est cohérent, mais deux commandes de la gate opérateur utilisent des backticks non échappés dans des chaînes Bash entre guillemets doubles. Bash les a donc interprétés comme des substitutions de commande au lieu de les transmettre littéralement à `grep`.
## Baseline
Version observée par l'opérateur :
```text
0.0.1-alpha.4
```
Le delta `0.0.1-alpha.4` a été appliqué après commit de `0.0.1-alpha.3` avec son history.
## Validation opérateur observée
Les contrôles structurels et Git suivants ont réussi :
```bash
test "$(cat VERSION)" = "0.0.1-alpha.4"
test -f docs/rules/300-DOCUMENTATION.md
grep -Fx '<!-- file: docs/rules/300-DOCUMENTATION.md -->' docs/rules/300-DOCUMENTATION.md
grep -F '`ROADMAP.md` décrit la trajectoire macro du projet' docs/rules/300-DOCUMENTATION.md
grep -F '`version` est une révision interne du fichier. Elle est indépendante de `VERSION`' docs/rules/300-DOCUMENTATION.md
grep -F 'Un snapshot historique MUST NOT être réécrit silencieusement' docs/rules/300-DOCUMENTATION.md
grep -F 'La documentation est une aide au développement et à la maintenance, pas une fin en soi.' docs/rules/300-DOCUMENTATION.md
git diff --check
git add VERSION RULES.md docs/rules/000-README.md docs/rules/300-DOCUMENTATION.md \
deltas/0.0.1/alpha.4.md
git diff --cached --check
git status --short
```
`git diff --check` et `git diff --cached --check` n'ont produit aucun diagnostic.
La sortie finale observée avant ajout du présent history était :
```text
M RULES.md
M VERSION
A deltas/0.0.1/alpha.4.md
M docs/rules/000-README.md
A docs/rules/300-DOCUMENTATION.md
```
## Défaut de gate identifié
La commande suivante contenait des backticks non échappés dans une chaîne entre guillemets doubles :
```bash
grep -F "`USAGE.md` est un guide d'utilisation durable" docs/rules/300-DOCUMENTATION.md
```
Bash a tenté d'exécuter `USAGE.md` comme une commande. Le `grep` résultant a malgré tout trouvé un fragment plus court, produisant un faux positif.
La commande suivante avait le même défaut :
```bash
grep -F "PGR MUST NOT créer d'arborescence `fr/`, `en/`, `de/`" docs/rules/300-DOCUMENTATION.md
```
Bash a tenté d'exécuter `fr/`, `en/` et `de/` ; l'assertion attendue n'a donc pas été validée.
## Conséquence
`alpha.4` est enregistrée en FAIL pour défaut de gate opérateur. Le contenu normatif n'a pas besoin d'être réécrit.
La tranche suivante est `0.0.1-alpha.4.fix.1`, limitée à une revalidation correcte des assertions de `alpha.4` avec un quoting Bash sûr. Aucun REPLAN n'est requis.