Runbook de recuperação de lançamento
Procedimentos de recuperação, estágio por estágio, para um lançamento que falha no meio do processo sob o modelo de lançamento aditivo, sem reescrever o histórico publicado.
Este runbook restaura um estado funcional quando um lançamento vX.Y.Z de
ahmed-g-gad/apothem falha no meio do caminho. Ele segue o mesmo modelo de
lançamento que o runbook do ciclo de lançamento:
um modelo aditivo. Cada lançamento adiciona um commit em main e uma tag
assinada e anotada; o push da tag executa os fluxos de trabalho de lançamento e
do npm. Nada recebe force-push, e o histórico em main nunca é reescrito.
O histórico publicado é permanente. Toda tag de lançamento, todo GitHub Release
e toda versão do npm que o projeto publicou permanecem publicados.
As versões do npm são imutáveis: um name@version publicado nunca pode ser
substituído, e um número de versão que foi despublicado nunca pode ser usado
novamente. Por isso, a recuperação avança com um novo lançamento de patch; ela
não exclui nem redireciona nada que um usuário já possa ter instalado.
1. Taxonomia de estágios
| Estágio | Ação | Modo de falha | Caminho de recuperação |
|---|---|---|---|
| 1 | Aterrissar o commit de lançamento em main (§2.1 do runbook do ciclo de lançamento) | O CI falha no commit de lançamento | Corrija para frente com outro commit em main; não marque a tag até que o CI esteja verde |
| 2 | Enviar a tag assinada e anotada | O push é rejeitado, ou a tag não está assinada ou está no commit errado | §2 abaixo |
| 3 | release.yml compila, assina e publica o GitHub Release | Um job falha, ou há ativos ausentes | §3 abaixo |
| 4 | publish-npm.yml publica @ahmed-g-gad/apothem (executa no mesmo push da tag) | A publicação falha | §3 abaixo |
| 5 | Pages e metadados do repositório | O site ou os metadados estão desatualizados | §3 abaixo |
Cada ação de recuperação é idempotente. Executá-la em um estado limpo não faz nada; executá-la em um estado parcial restaura a condição esperada após o estágio.
2. Recuperação da tag
Diagnostique a 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 checkO que fazer depende de algo ter sido publicado ou não a partir da tag:
-
Nada publicado ainda (o fluxo de trabalho de lançamento falhou antes do seu job de publicação, e
publish-npm.ymlnão publicou): exclua a tag e marque novamente o mesmo commit com-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 -
Algo publicado (um GitHub Release com ativos, ou a versão do npm): nunca mova, exclua ou reutilize a tag. Corrija para frente com
vX.Y.(Z+1).
Um nome de tag nunca é reutilizado para um commit diferente.
3. Recuperação de publicadores
Cada publicador é tentado novamente de forma independente:
| Superfície | Diagnóstico | Recuperação |
|---|---|---|
| Fluxo de trabalho de lançamento | gh run view <run-id> --log nomeia o job que falhou | gh run rerun <run-id> --failed. Uma falha em Check the plugin version changed with the plugin significa que a versão não foi incrementada: consulte a tabela de falhas do runbook do ciclo de lançamento |
| GitHub Release | gh release view vX.Y.Z --json tagName,isDraft,isPrerelease,assets | Execute novamente o job publish GitHub Release; ele edita o lançamento existente e reenvia os ativos com --clobber |
| npm | npm view @ahmed-g-gad/apothem version e npx @ahmed-g-gad/[email protected] --version | Execute novamente publish-npm.yml para vX.Y.Z (gh workflow run publish-npm.yml --field tag=vX.Y.Z) depois de confirmar a publicação confiável do npm para o pacote. Se a versão já estiver no registro, o fluxo de trabalho pula a publicação, pois as versões do npm são imutáveis |
| Pages | gh run list --workflow=publish-static-site.yml --limit=1 e curl -sSI https://apothem.ahmedgad.com/ | Execute novamente publish-static-site.yml; verifique se o CNAME ainda resolve para ahmed-g-gad.github.io |
| Metadados do repositório | gh repo view ahmed-g-gad/apothem --json description,homepageUrl,repositoryTopics,visibility | Corrija a descrição, a página inicial e os tópicos no local; nunca recrie o repositório |
4. Reversão
Um lançamento defeituoso é revertido lançando a sua correção, não removendo-o:
-
Reverta os commits problemáticos em
main(um commit de reversão comum). -
Lance
vX.Y.(Z+1)com o runbook do ciclo de lançamento. -
Marque a versão defeituosa: adicione uma nota
### Yankedà seção dela noCHANGELOG.md, edite as notas do GitHub Release dela para apontar para a correção e descontinue-a no npm:npm deprecate @ahmed-g-gad/[email protected] "Contains <defect>; use X.Y.(Z+1)"
A tag, o GitHub Release e a versão do npm defeituosos permanecem publicados, de modo que as instalações fixadas e os builds reproduzíveis continuam sendo resolvidos. Registre a reversão como um incidente de lançamento.
5. A regra de fachada de lançamento
A regra de fachada de lançamento do repositório (a seção Release Facade das instruções para contribuidores) estabelece o modelo aditivo acima: toda tag, todo GitHub Release e toda versão do npm que o projeto publicou permanecem publicados. O requisito de apenas a versão atual abrange o que as superfícies públicas afirmam. Este runbook nunca exclui nem reescreve tags, GitHub Releases ou versões do npm publicados.
6. Referências cruzadas
- Procedimento de lançamento: runbook do ciclo de lançamento.
- Política de lançamento: política de engenharia de lançamento.
- Objetos de tag e como verificar cada um: a seção de assinatura de lançamentos do SECURITY.md.
- Configuração do Pages:
site/content/docs/runbooks/pages-enablement.mdx.