Runbook de recuperación de lanzamientos
Procedimientos de recuperación, etapa por etapa, para un lanzamiento que falla a mitad de camino bajo el modelo de lanzamiento aditivo, sin reescribir el historial publicado.
Este runbook restaura un estado funcional cuando un lanzamiento vX.Y.Z de
ahmed-g-gad/apothem falla a mitad de camino. Sigue el mismo modelo de
lanzamiento que el runbook del ciclo de lanzamiento:
un modelo aditivo. Cada lanzamiento agrega un commit en main y una
etiqueta anotada y firmada; el push de la etiqueta ejecuta los flujos de trabajo
de lanzamiento y de npm. No se hace force-push de nada, y el historial de main
nunca se reescribe.
El historial publicado es permanente. Cada etiqueta de lanzamiento, GitHub
Release y versión de npm que el proyecto ha publicado sigue publicada. Las versiones de npm son inmutables: un name@version
publicado nunca puede reemplazarse, y un número de versión cuya publicación se
retiró nunca puede volver a usarse. Por lo tanto, la recuperación avanza con un
nuevo lanzamiento de parche; no elimina ni redirige nada que un usuario ya pueda
haber instalado.
1. Taxonomía de etapas
| Etapa | Acción | Modo de fallo | Ruta de recuperación |
|---|---|---|---|
| 1 | Llevar el commit de lanzamiento a main (§2.1 del runbook del ciclo de lanzamiento) | CI falla en el commit de lanzamiento | Corrige hacia adelante con otro commit en main; no etiquetes hasta que CI esté en verde |
| 2 | Hacer push de la etiqueta anotada y firmada | El push se rechaza, o la etiqueta no está firmada o está en el commit equivocado | §2 más abajo |
| 3 | release.yml compila, firma y publica el GitHub Release | Un trabajo falla, o faltan recursos | §3 más abajo |
| 4 | publish-npm.yml publica @ahmed-g-gad/apothem (se ejecuta con el mismo push de la etiqueta) | La publicación falla | §3 más abajo |
| 5 | Pages y metadatos del repositorio | El sitio o los metadatos están desactualizados | §3 más abajo |
Cada acción de recuperación es idempotente. Ejecutarla sobre un estado limpio no tiene ningún efecto; ejecutarla sobre un estado parcial restaura la condición esperada posterior a la etapa.
2. Recuperación de la etiqueta
Diagnostica la etiqueta:
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 checkQué hacer depende de si se publicó algo a partir de la etiqueta:
-
Todavía no se publicó nada (el flujo de trabajo de lanzamiento falló antes de su trabajo de publicación, y
publish-npm.ymlno publicó): elimina la etiqueta y vuelve a etiquetar el mismo commit con-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 -
Se publicó algo (un GitHub Release con recursos, o la versión de npm): nunca muevas, elimines ni reutilices la etiqueta. Corrige hacia adelante con
vX.Y.(Z+1).
Un nombre de etiqueta nunca se reutiliza para un commit distinto.
3. Recuperación de publicadores
Cada publicador se reintenta por separado:
| Superficie | Diagnóstico | Recuperación |
|---|---|---|
| Flujo de trabajo de lanzamiento | gh run view <run-id> --log nombra el trabajo que falla | gh run rerun <run-id> --failed. Un fallo en Check the plugin version changed with the plugin significa que la versión no se incrementó: consulta la tabla de fallos del runbook del ciclo de lanzamiento |
| GitHub Release | gh release view vX.Y.Z --json tagName,isDraft,isPrerelease,assets | Vuelve a ejecutar el trabajo publish GitHub Release; este edita el lanzamiento existente y vuelve a subir los recursos con --clobber |
| npm | npm view @ahmed-g-gad/apothem version y npx @ahmed-g-gad/[email protected] --version | Vuelve a ejecutar publish-npm.yml para vX.Y.Z (gh workflow run publish-npm.yml --field tag=vX.Y.Z) después de confirmar la publicación de confianza de npm para el paquete. Si la versión ya está en el registro, el flujo de trabajo omite la publicación, ya que las versiones de npm son inmutables |
| Pages | gh run list --workflow=publish-static-site.yml --limit=1 y curl -sSI https://apothem.ahmedgad.com/ | Vuelve a ejecutar publish-static-site.yml; verifica que el CNAME siga resolviendo a ahmed-g-gad.github.io |
| Metadatos del repositorio | gh repo view ahmed-g-gad/apothem --json description,homepageUrl,repositoryTopics,visibility | Corrige en su lugar la descripción, la página de inicio y los temas; nunca recrees el repositorio |
4. Reversión
Un lanzamiento defectuoso se revierte lanzando su corrección, no eliminándolo:
-
Revierte los commits problemáticos en
main(un commit de reversión ordinario). -
Crea el lanzamiento
vX.Y.(Z+1)con el runbook del ciclo de lanzamiento. -
Marca la versión defectuosa: agrega una nota
### Yankeda su sección deCHANGELOG.md, edita las notas de su GitHub Release para que apunten a la corrección y márcala como obsoleta en npm:npm deprecate @ahmed-g-gad/[email protected] "Contains <defect>; use X.Y.(Z+1)"
La etiqueta, el GitHub Release y la versión de npm defectuosos siguen publicados, de modo que las instalaciones fijadas y las compilaciones reproducibles se siguen resolviendo. Registra la reversión como un incidente de lanzamiento.
5. La regla de fachada de lanzamiento
La regla de fachada de lanzamiento del repositorio (la sección Release Facade de las instrucciones para colaboradores) enuncia el modelo aditivo descrito arriba: todas las etiquetas, GitHub Releases y versiones de npm publicados siguen publicados. El requisito de solo la versión actual abarca lo que dicen las superficies públicas. Este runbook nunca elimina ni reescribe etiquetas, GitHub Releases ni versiones de npm publicados.
6. Referencias cruzadas
- Procedimiento de lanzamiento: runbook del ciclo de lanzamiento.
- Política de lanzamiento: política de ingeniería de lanzamientos.
- Los objetos de etiqueta y cómo verificar cada uno: la sección de firma de lanzamientos de SECURITY.md.
- Configuración de Pages:
site/content/docs/runbooks/pages-enablement.mdx.