Runbook de récupération de publication
Procédures de récupération, étape par étape, pour une publication qui échoue en cours de route sous le modèle de publication additif, sans réécrire l'historique publié.
Ce runbook restaure un état fonctionnel lorsqu'une publication vX.Y.Z de
ahmed-g-gad/apothem échoue en cours de route. Il suit le même modèle de
publication que le runbook du cycle de publication :
un modèle additif. Chaque publication ajoute un commit sur main et une
étiquette annotée et signée ; le push de l'étiquette exécute les flux de travail
de publication et npm. Aucun force-push n'est effectué, et l'historique de
main n'est jamais réécrit.
L'historique publié est permanent. Chaque étiquette de publication, chaque
GitHub Release et chaque version npm que le projet a publiés restent publiés. Les versions npm sont immuables : un name@version
publié ne peut jamais être remplacé, et un numéro de version dépublié ne peut
jamais être réutilisé. La récupération avance donc avec une nouvelle publication
de niveau patch ; elle ne supprime ni ne réaffecte rien de ce qu'un utilisateur
a peut-être déjà installé.
1. Taxonomie des étapes
| Étape | Action | Mode de défaillance | Chemin de récupération |
|---|---|---|---|
| 1 | Faire atterrir le commit de publication sur main (§2.1 du runbook du cycle de publication) | La CI échoue sur le commit de publication | Corrigez vers l'avant avec un autre commit sur main ; n'étiquetez pas tant que la CI n'est pas au vert |
| 2 | Pousser l'étiquette annotée et signée | Le push est rejeté, ou l'étiquette n'est pas signée ou se trouve sur le mauvais commit | §2 ci-dessous |
| 3 | release.yml compile, signe et publie le GitHub Release | Un job échoue, ou des ressources manquent | §3 ci-dessous |
| 4 | publish-npm.yml publie @ahmed-g-gad/apothem (s'exécute sur le même push d'étiquette) | La publication échoue | §3 ci-dessous |
| 5 | Pages et métadonnées du dépôt | Le site ou les métadonnées sont obsolètes | §3 ci-dessous |
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
Diagnostiquez l'étiquette :
git fetch origin --tags
git ls-remote origin refs/tags/vX.Y.Z
git cat-file -t vX.Y.Z # "tag" for an annotated tag
git tag -v vX.Y.Z # signature checkLa marche à suivre dépend de la question de savoir si quelque chose a été publié à partir de l'étiquette :
-
Rien n'a encore été publié (le flux de travail de publication a échoué avant son job de publication, et
publish-npm.ymln'a rien publié) : supprimez l'étiquette et ré-étiquetez le même commit avec-a -s.git push --delete origin vX.Y.Z git tag -d vX.Y.Z git tag -a -s vX.Y.Z -m "vX.Y.Z" <release-commit-sha> git push origin vX.Y.Z -
Quelque chose a été publié (un GitHub Release avec des ressources, ou la version npm) : ne déplacez, ne supprimez et ne réutilisez jamais l'étiquette. Corrigez vers l'avant avec
vX.Y.(Z+1).
Un nom d'étiquette n'est jamais réutilisé pour un commit différent.
3. Récupération des éditeurs
Chaque éditeur est relancé séparément :
| Surface | Diagnostic | Récupération |
|---|---|---|
| Flux de travail de publication | gh run view <run-id> --log nomme le job en échec | gh run rerun <run-id> --failed. Un échec à Check the plugin version changed with the plugin signifie que la version n'a pas été incrémentée : voir le tableau des échecs du runbook du cycle de publication |
| GitHub Release | gh release view vX.Y.Z --json tagName,isDraft,isPrerelease,assets | Relancez le job publish GitHub Release ; il modifie la publication existante et téléverse de nouveau les ressources avec --clobber |
| npm | npm view @ahmed-g-gad/apothem version et npx @ahmed-g-gad/[email protected] --version | Relancez publish-npm.yml pour vX.Y.Z (gh workflow run publish-npm.yml --field tag=vX.Y.Z) après avoir confirmé la publication de confiance npm pour le paquet. Si la version est déjà sur le registre, le flux de travail ignore la publication, puisque les versions npm sont immuables |
| 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 du dépôt | 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 jamais le dépôt |
4. Retour arrière
Une publication défectueuse est annulée en publiant son correctif, et non en la retirant :
-
Annulez les commits fautifs sur
main(un commit d'annulation ordinaire). -
Produisez
vX.Y.(Z+1)avec le runbook du cycle de publication. -
Marquez la version défectueuse : ajoutez une note
### Yankedà sa section deCHANGELOG.md, modifiez les notes de son GitHub Release pour qu'elles pointent vers le correctif, et dépréciez-la sur npm :npm deprecate @ahmed-g-gad/[email protected] "Contains <defect>; use X.Y.(Z+1)"
L'étiquette, le GitHub Release et la version npm défectueux restent publiés, de sorte que les installations épinglées et les compilations reproductibles continuent de se résoudre. Consignez le retour arrière comme un incident de publication.
5. La règle de façade de publication
La règle de façade de publication du dépôt (la section Release Facade des instructions destinées aux contributeurs) énonce le modèle additif ci-dessus : chaque étiquette publiée, chaque GitHub Release publié et chaque version npm publiée restent en place. Son exigence de n'afficher que la version courante porte sur ce qu'affichent les surfaces publiques. Ce runbook ne supprime ni ne réécrit jamais une étiquette publiée, un GitHub Release publié ou une version npm publiée.
6. Références croisées
- Procédure de publication : runbook du cycle de publication.
- Politique de publication : politique d'ingénierie de publication.
- Les objets étiquettes et la façon de vérifier chacun d'eux : la section sur la signature des publications de SECURITY.md.
- Configuration de Pages :
site/content/docs/runbooks/pages-enablement.mdx.