Runbook de récupération de version

Procédures de récupération pour restaurer le dépôt lorsqu'une séquence de version échoue en cours de route, avec des diagnostics étape par étape.

Ce runbook restaure ahmed-g-gad/apothem à un état fonctionnel lorsqu'une séquence de version par remise-à-zéro-sur-place échoue en cours de route. Le dépôt public n'est ni supprimé ni recréé pendant la version. La récupération dépend de l'étiquette de sécurité d'historique propre à la version, du clone local du mainteneur et de l'état des gestionnaires de paquets en aval.

1. Taxonomie des étapes

Étape	Action	Mode de défaillance	Chemin de récupération
1	Capturer et pousser l'étiquette de sécurité d'historique	L'étiquette est absente, non signée ou pointe vers le mauvais graphe	Recréer l'étiquette depuis le point de fusion antérieur à l'écrasement avant de déplacer `main`
2	Vérifier la CI, la forteresse d'audit, l'état des paquets et le changelog	Une porte quelconque échoue	Arrêtez ; corrigez en local ; ne déplacez pas `main`
3	Déplacer `main` vers l'unique commit de version signé	Le force-with-lease échoue, le commit n'est pas signé ou le message du commit est erroné	Réinitialisez `main` local sur le commit signé prévu et réessayez avec un lease neuf
4	Publier GitHub Release, Pages, npm et les métadonnées	Un publicateur ou une surface de vérification échoue	Conservez le commit de version ; relancez uniquement le publicateur en échec après avoir consigné l'échec

Chaque action de récupération est idempotente. L'exécuter sur un état propre est sans effet ; l'exécuter sur un état partiel restaure la condition attendue après l'étape.

2. Récupération de l'étiquette de sécurité

Vérifiez l'étiquette de sécurité avant toute réécriture de l'historique :

git fetch origin --tags
git show --summary --show-signature <history-safety-tag>
git merge-base --is-ancestor origin/main <history-safety-tag>

Attendu : l'étiquette existe, la vérification de la signature réussit lorsque l'étiquette est signée, et l'intégralité du graphe antérieur à l'écrasement est accessible depuis l'étiquette. Si l'étiquette est absente en local mais présente en distant, récupérez-la. Si elle est absente en distant, arrêtez la version et recréez-la avant de toucher à main :

git tag -s <history-safety-tag> <pre-squash-commit>
git push origin <history-safety-tag>

3. Récupération de la branche principale

Diagnostiquez l'état de main public :

gh api repos/ahmed-g-gad/apothem/commits/main \
  --jq '.sha, .commit.message, .commit.verification.verified, .commit.verification.reason'

Attendu après la bascule : le message est exactement release: Apothem <release-version> et verification.verified vaut true.

Si le push force-with-lease a échoué avant de modifier GitHub, laissez le distant tel quel, récupérez-le, reconstruisez le commit de version signé en local, et ne réessayez qu'une fois que le lease correspond :

git fetch origin main
git push --force-with-lease=main:<expected-remote-sha> origin main

Si le push a abouti avec un commit non signé ou non vérifié, corrigez la configuration de signature locale, recréez le commit de version depuis le même arbre, et faites de nouveau un force-push avec un lease. Ne supprimez pas l'étiquette de sécurité.

4. Récupération des publicateurs

Chaque publicateur est réessayé indépendamment une fois que le commit de version GitHub est vérifié :

Surface	Diagnostic	Récupération
GitHub Release	`gh release view <release-tag> --json tagName,isDraft,isPrerelease,assets`	Supprimez uniquement un brouillon malformé ; sinon, téléversez les ressources manquantes avec `gh release upload --clobber`
Étiquette de version	`git ls-remote origin refs/tags/<release-tag>` et `git tag -v <release-tag>`	Ré-étiquetez depuis le même SHA avec `-a -s` si l'étiquette est absente ou non signée ; ne réutilisez jamais un nom d'étiquette pour un commit différent
npm	`npm view @ahmed-g-gad/apothem version` et `npx @ahmed-g-gad/apothem@<version> --version`	Relancez `publish-npm.yml` pour `<release-tag>` après avoir confirmé le npm Trusted Publishing pour `@ahmed-g-gad/apothem`
Pages	`gh run list --workflow=publish-static-site.yml --limit=1` et `curl -sSI https://apothem.ahmedgad.com/`	Relancez `publish-static-site.yml` ; vérifiez que le CNAME résout toujours vers `ahmed-g-gad.github.io`
Métadonnées GitHub	`gh repo view ahmed-g-gad/apothem --json description,homepageUrl,repositoryTopics,visibility`	Corrigez la description, la page d'accueil et les sujets sur place ; ne recréez pas le dépôt

5. Retour arrière

Le retour arrière est l'ultime recours. Préférez d'abord la récupération ciblée des publicateurs. Si l'unique commit de version doit être annulé, restaurez main depuis l'étiquette de sécurité :

git fetch origin --tags
git switch main
git reset --hard <history-safety-tag>
git push --force-with-lease origin main

Après le retour arrière, relancez la CI, réappliquez la protection de branche si GitHub signale une dérive, et consignez le retour arrière comme un incident bloquant la version. Ne conservez l'étiquette de version que si les artefacts de la version restent valides ; sinon, supprimez la version et l'étiquette malformées avant de réessayer.

6. Références croisées

Configuration de Pages : site/content/docs/runbooks/pages-enablement.mdx.
Procédure de version : site/content/docs/runbooks/release-cycle.mdx.
Recettes d'empaquetage : packaging/README.md.
Ancre de récupération : l'étiquette de sécurité d'historique propre à la version.