Questa pagina è tradotta dalla documentazione inglese. Comandi, identificatori ed esempi restano invariati. Runtime 7.24.4 · SDK 2.6.7. Testo inglese

Runbook di rollback del rilascio

Stato: attivo Ambito: pubblico, stato attuale Ultima revisione: 2026-09-03 Responsabile: ingegneria di rilascio di AX Code

Questo runbook descrive come ritirare un rilascio stabile pubblicato (canale latest) della CLI di AX Code e ripristinare quello precedente. I rilasci di prerelease (canale beta) non toccano il tap Homebrew né winget, quindi per riportarli indietro serve soltanto il passo GitHub descritto sotto.

Preferisci un hotfix in avanti (pubblica vX.Y.Z+1) per i bug funzionali. Esegui il rollback soltanto per fallimenti di integrità del rilascio: artefatti rotti o firmati in modo errato, un installer corrotto, un errore di canale o di tag (per esempio un tag di prerelease pubblicato su latest) oppure una regressione grave senza una correzione rapida.

1. Congelare il canale

Metti in pausa gli ulteriori rilasci e le riprese di postpublish_only finché il rollback non è completo. Il workflow di rilascio rifiuta di sostituire gli asset di un rilascio già pubblicato, quindi nessuna riesecuzione concorrente può sovrascrivere lo stato che si sta riportando indietro.

2. Ripuntare il rilascio GitHub

Contrassegna il rilascio difettoso come prerelease, così latest risolve al tag precedente, e ripristina le note di rilascio precedenti se sono state sovrascritte:

gh release edit "vX.Y.Z" --repo defai-digital/ax-code --prerelease
gh release edit "vX.Y.(Z-1)" --repo defai-digital/ax-code --latest

Se gli asset del rilascio difettoso sono corrotti o firmati in modo errato, eliminali anche, così nessun installer può scaricarli:

gh release delete-asset "vX.Y.Z" "<asset-name>" --repo defai-digital/ax-code

Non cancellare l’oggetto del rilascio stesso finché i suoi artefatti non sono stati indagati; gli asset firmati e i log del workflow sono l’evidenza per il postmortem.

3. Ripristinare il tap Homebrew

bash .github/scripts/update-homebrew.sh ha inviato un commit della formula al repository condiviso defai-digital/homebrew-tap. Ripristina quel commit, così brew upgrade ax-code serve di nuovo la versione precedente. Il repository precedente defai-digital/homebrew-ax-code contiene soltanto metadati di migrazione; non ripristinare la sua formula:

git -C homebrew-tap revert --no-edit <formula-commit>

Verifica poi la convergenza con il job di smoke di Homebrew (.github/workflows/install-matrix-smoke.yml) rispetto alla versione ripristinata.

4. Ripristinare i manifest winget

I manifest di winget vengono inviati dai manutentori a microsoft/winget-pkgs a partire dallo ZIP dei manifest allegato al rilascio GitHub. Se la versione difettosa è già stata accettata, apri una PR che ripristina quei file di manifest. Se è ancora in revisione, chiudi la PR. Il caricamento --clobber sul rilascio sostituisce soltanto lo ZIP allegato, mai il pacchetto pubblicato.

5. Comunicare

Pubblica una nota breve nella discussione del rilascio e in ogni canale di supporto: versioni interessate, versione ripristinata e istruzioni di reinstallazione:

• Homebrew: brew update && brew upgrade ax-code (oppure brew uninstall ax-code && brew install ax-code).
• Windows e gli altri: riesegui l’installer fissato dalla pagina del rilascio precedente; l’installer fallisce in modo chiuso se la firma non coincide e avvia un minisign fissato e controllato con SHA-256.

6. Verificare lo stato ripristinato

1. Conferma che il rilascio GitHub latest punti al tag precedente e che ogni asset risulti verificato:

   gh release download "vX.Y.(Z-1)" --repo defai-digital/ax-code -p '*.zip' -p '*.minisig'
   minisign -V -p docs/release/ax-minisign.pub -m ax-code-darwin-arm64.zip -x ax-code-darwin-arm64.zip.minisig

2. Conferma che la formula Homebrew serva la versione ripristinata e si installi in modo pulito su un runner pulito (lo fa il workflow di smoke della matrice di installazione).

3. Conferma che ax-code --version su un’installazione nuova riporti la versione ripristinata e superi ax-code doctor.

7. Postmortem

Registra che cosa ha superato i gate di rilascio ed è comunque stato distribuito rotto, e apri le correzioni su .github/workflows/release.yml (validazione, copertura degli smoke) prima del rilascio successivo. Aggiorna questo runbook se un passo non ha funzionato come è scritto.