127 lines
4.9 KiB
Markdown
127 lines
4.9 KiB
Markdown
<!-- file: docs/templates/006-OPERATOR_COMMAND_HANDOFF.md -->
|
|
<!-- version: 1 -->
|
|
|
|
# Pattern — handoff des commandes opérateur
|
|
|
|
## Usage
|
|
|
|
Ce pattern matérialise la sortie opérateur exigée par [`210-WORKFLOW.md`](../rules/210-WORKFLOW.md) après production d'un history et pendant une clôture stable. Son objectif est d'éviter que l'opérateur doive demander séparément quelles commandes exécuter entre le history reçu, son commit, le delta suivant et, pour une stable, le tag puis la vérification post-tag.
|
|
|
|
Le pattern est un guide de rendu : `210-WORKFLOW.md` reste l'owner normatif.
|
|
|
|
## Informations à résoudre avant le rendu
|
|
|
|
Le générateur doit déterminer depuis les preuves disponibles :
|
|
|
|
```text
|
|
project
|
|
X.Y.Z
|
|
tranche courante
|
|
statut du history
|
|
archive history réellement livrée
|
|
message de commit attendu
|
|
remote Git établi
|
|
branche Git établie
|
|
delta/fix suivant déjà livré ou non
|
|
stable obtenue ou non
|
|
tag canonique attendu
|
|
forge/archive post-tag applicable
|
|
preuve publish.* attendue ou non
|
|
```
|
|
|
|
Une valeur non établie ne doit pas être inventée. Si le remote ou la branche manque, le rendu peut d'abord fournir une commande de découverte telle que `git remote -v` ou `git branch --show-current`, puis demander d'utiliser la valeur réellement observée ; il ne doit pas transformer silencieusement un exemple `origin/master` en règle universelle.
|
|
|
|
## Fermeture d'une tranche non stable
|
|
|
|
Lorsque le history est livré sous forme de ZIP et que remote/branche sont établis, le bloc remis suit cette forme :
|
|
|
|
```bash
|
|
unzip -o <project>-<X.Y.Z>-<tranche>.history.zip -d .
|
|
|
|
git add -A
|
|
git diff --cached --check
|
|
git status --short
|
|
git commit -m "<message attendu>"
|
|
git push <remote> <branche>
|
|
```
|
|
|
|
Si le delta suivant ou le fix est déjà livré dans la même réponse, son application est affichée **après** le bloc de commit/push :
|
|
|
|
```bash
|
|
unzip -o <archive delta suivante>.delta.zip -d .
|
|
```
|
|
|
|
L'ordre visuel du rendu doit refléter l'ordre autorisé : history → commit/push → delta suivant.
|
|
|
|
## Tranche échouée suivie d'un fix
|
|
|
|
Un `FAIL`, `PARTIAL` ou `BLOCKED` est d'abord committé avec l'identité de la tranche observée, puis le fix est appliqué. Exemple générique :
|
|
|
|
```bash
|
|
unzip -o <project>-<X.Y.Z>-alpha.2.history.zip -d .
|
|
|
|
git add -A
|
|
git diff --cached --check
|
|
git status --short
|
|
git commit -m "X.Y.Z-alpha.2"
|
|
git push <remote> <branche>
|
|
|
|
unzip -o <project>-<X.Y.Z>-alpha.2.fix.1.delta.zip -d .
|
|
```
|
|
|
|
Le history `FAIL` n'est jamais remplacé par le futur `PASS` du fix.
|
|
|
|
## Première clôture qui établit réellement la stable
|
|
|
|
Quand `rel.N[/fix.M]` obtient le premier `PASS` stable, le commit porte l'identité produit :
|
|
|
|
```bash
|
|
unzip -o <project>-<X.Y.Z>-<rel.N[/fix.M]>.history.zip -d .
|
|
|
|
git add -A
|
|
git diff --cached --check
|
|
git status --short
|
|
git commit -m "X.Y.Z"
|
|
git push <remote> <branche>
|
|
```
|
|
|
|
Le tag vient ensuite. Si la politique locale utilise un tag annoté, le bloc type est :
|
|
|
|
```bash
|
|
git status --short
|
|
git rev-parse HEAD
|
|
git tag -a vX.Y.Z -m "vX.Y.Z"
|
|
git push <remote> vX.Y.Z
|
|
|
|
git rev-list -n 1 vX.Y.Z
|
|
git ls-remote --exit-code --tags <remote> refs/tags/vX.Y.Z
|
|
git ls-remote <remote> 'refs/tags/vX.Y.Z^{}'
|
|
```
|
|
|
|
Pour un tag annoté, `refs/tags/vX.Y.Z` peut identifier l'objet tag et différer du SHA du commit. La référence déréférencée `refs/tags/vX.Y.Z^{}` est celle qui doit être comparée au commit stable.
|
|
|
|
Si le projet utilise volontairement une autre forme de tag, le bloc est adapté à cette politique au lieu d'imposer `git tag -a`.
|
|
|
|
## Remise nécessaire pour `publish.*`
|
|
|
|
Après création/push du tag et génération de l'archive par la forge, le générateur indique explicitement ce qu'il attend. Pour le cas source-archive usuel :
|
|
|
|
```text
|
|
1. télécharger depuis la forge le ZIP correspondant exactement au tag vX.Y.Z ;
|
|
2. fournir ce ZIP au générateur ;
|
|
3. fournir les sorties Git du commit/tag local et distant exécutées ci-dessus ;
|
|
4. fournir toute preuve de publication supplémentaire exigée localement.
|
|
```
|
|
|
|
Le générateur vérifie alors l'archive publiée, calcule son empreinte dans son propre environnement lorsque possible et produit le rapport `publish.*` à partir des observations réelles. Le rapport reste extérieur au tag qu'il vérifie.
|
|
|
|
## Après `publish.* PASS`
|
|
|
|
Si une version suivante est déjà décidée et son prompt existe dans la stable, le générateur remet automatiquement la phrase de nouvelle session définie par [`003-NEW_SESSION_PROMPT.md`](003-NEW_SESSION_PROMPT.md), avec les noms réels du ZIP taggé, du rapport post-tag et du prompt versionné.
|
|
|
|
Si l'horizon reste ouvert, il remet à la place le handoff ou la consigne de revue d'horizon applicable sans inventer de prochaine version.
|
|
|
|
## Critère de qualité
|
|
|
|
Le handoff est correct lorsque l'opérateur peut passer du history reçu au commit, au delta suivant ou à la publication sans devoir deviner une commande, un message de commit, un ordre d'application ou un artefact à fournir, tout en conservant explicites les valeurs Git qui ne sont pas encore établies.
|