Runbook pemulihan rilis

Prosedur pemulihan untuk rilis yang gagal di tengah jalan di bawah model rilis aditif, tahap demi tahap, tanpa menulis ulang riwayat yang telah dipublikasikan.

Runbook ini memulihkan keadaan yang berfungsi ketika rilis vX.Y.Z dari ahmed-g-gad/apothem gagal di tengah jalan. Runbook ini mengikuti model rilis yang sama dengan runbook siklus rilis: model aditif. Setiap rilis menambahkan satu commit di main dan satu tag beranotasi yang ditandatangani; push tag menjalankan alur kerja rilis dan npm. Tidak ada yang di-force-push, dan riwayat di main tidak pernah ditulis ulang.

Riwayat yang telah dipublikasikan bersifat permanen. Setiap tag rilis, GitHub Release, dan versi npm yang telah dipublikasikan proyek tetap terpublikasi. Versi npm tidak dapat diubah: name@version yang telah dipublikasikan tidak pernah dapat diganti, dan nomor versi yang pernah di-unpublish tidak pernah dapat digunakan lagi. Karena itu, pemulihan bergerak maju dengan rilis patch baru; pemulihan tidak menghapus atau mengarahkan ulang apa pun yang mungkin sudah dipasang pengguna.

1. Taksonomi tahap

Tahap	Tindakan	Mode kegagalan	Jalur pemulihan
1	Daratkan commit rilis di `main` (§2.1 dari runbook siklus rilis)	CI gagal pada commit rilis	Perbaiki maju dengan commit lain di `main`; jangan membuat tag sampai CI hijau
2	Push tag beranotasi yang ditandatangani	Push ditolak, atau tag tidak ditandatangani atau berada pada commit yang salah	§2 di bawah
3	`release.yml` membangun, menandatangani, dan memublikasikan GitHub Release	Sebuah job gagal, atau aset hilang	§3 di bawah
4	`publish-npm.yml` memublikasikan `@ahmed-g-gad/apothem` (berjalan pada push tag yang sama)	Publikasi gagal	§3 di bawah
5	Pages dan metadata repositori	Situs atau metadata usang	§3 di bawah

Setiap tindakan pemulihan bersifat idempoten. Menjalankannya pada keadaan bersih adalah no-op; menjalankannya pada keadaan parsial memulihkan kondisi pasca-tahap yang diharapkan.

2. Pemulihan tag

Diagnosis 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 check

Apa yang harus dilakukan bergantung pada apakah ada sesuatu yang telah dipublikasikan dari tag tersebut:

Belum ada yang dipublikasikan (alur kerja rilis gagal sebelum job publikasinya, dan publish-npm.yml tidak memublikasikan): hapus tag dan buat ulang tag pada commit yang sama dengan -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
```
Ada yang telah dipublikasikan (GitHub Release dengan aset, atau versi npm): jangan pernah memindahkan, menghapus, atau menggunakan ulang tag. Perbaiki maju dengan vX.Y.(Z+1).

Nama tag tidak pernah digunakan ulang untuk commit yang berbeda.

3. Pemulihan penerbit

Setiap penerbit dicoba ulang secara tersendiri:

Permukaan	Diagnostik	Pemulihan
Alur kerja rilis	`gh run view <run-id> --log` menyebutkan job yang gagal	`gh run rerun <run-id> --failed`. Kegagalan pada `Check the plugin version changed with the plugin` berarti versi belum dinaikkan: lihat tabel kegagalan di runbook siklus rilis
GitHub Release	`gh release view vX.Y.Z --json tagName,isDraft,isPrerelease,assets`	Jalankan ulang job `publish GitHub Release`; job ini menyunting rilis yang sudah ada dan mengunggah ulang aset dengan `--clobber`
npm	`npm view @ahmed-g-gad/apothem version` dan `npx @ahmed-g-gad/[email protected] --version`	Jalankan ulang `publish-npm.yml` untuk `vX.Y.Z` (`gh workflow run publish-npm.yml --field tag=vX.Y.Z`) setelah mengonfirmasi npm trusted publishing untuk paket tersebut. Jika versi sudah ada di registri, alur kerja melewati publikasi, karena versi npm tidak dapat diubah
Pages	`gh run list --workflow=publish-static-site.yml --limit=1` dan `curl -sSI https://apothem.ahmedgad.com/`	Jalankan ulang `publish-static-site.yml`; verifikasi bahwa CNAME masih ter-resolve ke `ahmed-g-gad.github.io`
Metadata repositori	`gh repo view ahmed-g-gad/apothem --json description,homepageUrl,repositoryTopics,visibility`	Tambal deskripsi, beranda, dan topik di tempat; jangan pernah membuat ulang repositori

4. Rollback

Rilis yang buruk di-rollback dengan merilis perbaikannya, bukan dengan menghapusnya:

Revert commit yang bermasalah di main (commit revert biasa).
Buat vX.Y.(Z+1) dengan runbook siklus rilis.
Tandai versi yang buruk: tambahkan catatan ### Yanked ke bagian CHANGELOG.md-nya, sunting catatan GitHub Release-nya agar menunjuk ke perbaikan, dan tandai versi itu usang (deprecate) di npm:
```
npm deprecate @ahmed-g-gad/[email protected] "Contains <defect>; use X.Y.(Z+1)"
```

Tag, GitHub Release, dan versi npm yang buruk tetap terpublikasi, sehingga pemasangan yang dipatok dan build yang dapat direproduksi tetap ter-resolve. Catat rollback sebagai insiden rilis.

5. Aturan fasad rilis

Aturan fasad rilis repositori (bagian Release Facade dari instruksi kontributor) menyatakan model aditif di atas: setiap tag, GitHub Release, dan versi npm yang telah dipublikasikan tetap terpublikasi. Persyaratan untuk hanya menampilkan versi saat ini berlaku untuk apa yang dinyatakan permukaan publik. Runbook ini tidak pernah menghapus atau menulis ulang tag, GitHub Release, atau versi npm yang telah dipublikasikan.

6. Referensi silang

Prosedur rilis: runbook siklus rilis.
Kebijakan rilis: kebijakan rekayasa rilis.
Objek tag dan cara memverifikasi masing-masing: bagian penandatanganan rilis di SECURITY.md.
Konfigurasi Pages: site/content/docs/runbooks/pages-enablement.mdx.

Runbook pemulihan rilis

1. Taksonomi tahapCopy Anchor Link

2. Pemulihan tagCopy Anchor Link

3. Pemulihan penerbitCopy Anchor Link

4. RollbackCopy Anchor Link

5. Aturan fasad rilisCopy Anchor Link