Runbook zur Release-Wiederherstellung
Wiederherstellungsverfahren für ein Release, das unter dem additiven Release-Modell mitten im Ablauf fehlschlägt, Stufe für Stufe und ohne veröffentlichten Verlauf umzuschreiben.
Dieses Runbook stellt einen funktionsfähigen Zustand wieder her, wenn ein
vX.Y.Z-Release von ahmed-g-gad/apothem auf halbem Weg fehlschlägt. Es folgt
demselben Release-Modell wie das
Runbook zum Release-Zyklus: einem additiven
Modell. Jedes Release fügt einen Commit auf main und ein signiertes,
annotiertes Tag hinzu; der Tag-Push führt die Release- und npm-Workflows aus.
Nichts wird per Force-Push übertragen, und der Verlauf auf main wird niemals
umgeschrieben.
Veröffentlichter Verlauf ist dauerhaft. Jedes Release-Tag, jedes GitHub Release
und jede npm-Version, die das Projekt veröffentlicht hat, bleibt veröffentlicht. npm-Versionen sind unveränderlich: Ein veröffentlichtes
name@version kann niemals ersetzt werden, und eine Versionsnummer, deren
Veröffentlichung zurückgezogen wurde, kann niemals wieder verwendet werden. Die
Wiederherstellung geht daher mit einem neuen Patch-Release nach vorn; sie löscht
nichts und richtet nichts neu aus, was ein Benutzer bereits installiert haben
könnte.
1. Stufentaxonomie
| Stufe | Aktion | Fehlermodus | Wiederherstellungspfad |
|---|---|---|---|
| 1 | Den Release-Commit auf main landen (§2.1 des Runbooks zum Release-Zyklus) | CI schlägt beim Release-Commit fehl | Mit einem weiteren Commit auf main nach vorn korrigieren; nicht taggen, bevor CI grün ist |
| 2 | Das signierte, annotierte Tag pushen | Der Push wird abgelehnt, oder das Tag ist unsigniert oder sitzt auf dem falschen Commit | §2 unten |
| 3 | release.yml baut, signiert und veröffentlicht das GitHub Release | Ein Job schlägt fehl, oder Assets fehlen | §3 unten |
| 4 | publish-npm.yml veröffentlicht @ahmed-g-gad/apothem (läuft beim selben Tag-Push) | Die Veröffentlichung schlägt fehl | §3 unten |
| 5 | Pages und Repository-Metadaten | Die Website oder die Metadaten sind veraltet | §3 unten |
Jede Wiederherstellungsaktion ist idempotent. Sie auf einem sauberen Zustand auszuführen, ist ein No-op; sie auf einem partiellen Zustand auszuführen, stellt die erwartete Bedingung nach der Stufe wieder her.
2. Tag-Wiederherstellung
Diagnostizieren Sie das Tag:
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 checkDas Vorgehen hängt davon ab, ob aus dem Tag etwas veröffentlicht wurde:
-
Noch nichts veröffentlicht (der Release-Workflow schlug vor seinem Publish-Job fehl, und
publish-npm.ymlhat nichts veröffentlicht): Löschen Sie das Tag und taggen Sie denselben Commit mit-a -sneu.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 -
Irgendetwas veröffentlicht (ein GitHub Release mit Assets oder die npm-Version): Verschieben Sie das Tag niemals, löschen Sie es niemals und verwenden Sie es niemals wieder. Korrigieren Sie nach vorn mit
vX.Y.(Z+1).
Ein Tag-Name wird niemals für einen anderen Commit wiederverwendet.
3. Publisher-Wiederherstellung
Jeder Publisher wird einzeln erneut versucht:
| Oberfläche | Diagnose | Wiederherstellung |
|---|---|---|
| Release-Workflow | gh run view <run-id> --log nennt den fehlgeschlagenen Job | gh run rerun <run-id> --failed. Ein Fehlschlag bei Check the plugin version changed with the plugin bedeutet, dass die Version nicht angehoben wurde: siehe die Fehlertabelle des Runbooks zum Release-Zyklus |
| GitHub Release | gh release view vX.Y.Z --json tagName,isDraft,isPrerelease,assets | Führen Sie den Job publish GitHub Release erneut aus; er bearbeitet das bestehende Release und lädt die Assets mit --clobber erneut hoch |
| npm | npm view @ahmed-g-gad/apothem version und npx @ahmed-g-gad/[email protected] --version | Führen Sie publish-npm.yml für vX.Y.Z erneut aus (gh workflow run publish-npm.yml --field tag=vX.Y.Z), nachdem Sie npm Trusted Publishing für das Paket bestätigt haben. Ist die Version bereits in der Registry, überspringt der Workflow die Veröffentlichung, da npm-Versionen unveränderlich sind |
| Pages | gh run list --workflow=publish-static-site.yml --limit=1 und curl -sSI https://apothem.ahmedgad.com/ | Führen Sie publish-static-site.yml erneut aus; verifizieren Sie, dass der CNAME weiterhin auf ahmed-g-gad.github.io auflöst |
| Repository-Metadaten | gh repo view ahmed-g-gad/apothem --json description,homepageUrl,repositoryTopics,visibility | Patchen Sie Beschreibung, Homepage und Themen an Ort und Stelle; erstellen Sie das Repository niemals neu |
4. Rollback
Ein fehlerhaftes Release wird zurückgerollt, indem seine Korrektur veröffentlicht wird, nicht indem es entfernt wird:
-
Nehmen Sie die verursachenden Commits auf
mainzurück (ein gewöhnlicher Revert-Commit). -
Erstellen Sie
vX.Y.(Z+1)mit dem Runbook zum Release-Zyklus. -
Kennzeichnen Sie die fehlerhafte Version: Fügen Sie ihrem
CHANGELOG.md-Abschnitt einen### Yanked-Hinweis hinzu, bearbeiten Sie die Notes ihres GitHub Release so, dass sie auf die Korrektur verweisen, und markieren Sie sie auf npm als veraltet:npm deprecate @ahmed-g-gad/[email protected] "Contains <defect>; use X.Y.(Z+1)"
Das fehlerhafte Tag, das GitHub Release und die npm-Version bleiben veröffentlicht, sodass gepinnte Installationen und reproduzierbare Builds weiterhin aufgelöst werden. Protokollieren Sie den Rollback als Release-Vorfall.
5. Die Release-Facade-Regel
Die Release-Facade-Regel des Repositorys (der Abschnitt Release Facade der Anweisungen für Mitwirkende) gibt das oben beschriebene additive Modell wieder: Jedes veröffentlichte Tag, jedes GitHub Release und jede npm-Version bleibt bestehen. Die Anforderung, nur die aktuelle Version auszuweisen, betrifft, was öffentliche Oberflächen aussagen. Dieses Runbook löscht niemals ein veröffentlichtes Tag, ein GitHub Release oder eine npm-Version und schreibt keines davon um.
6. Querverweise
- Release-Verfahren: Runbook zum Release-Zyklus.
- Release-Richtlinie: Release-Engineering-Richtlinie.
- Tag-Objekte und wie jedes einzelne verifiziert wird: der Abschnitt zur Release-Signierung in SECURITY.md.
- Pages-Konfiguration:
site/content/docs/runbooks/pages-enablement.mdx.