Esempio di Rollback Plan: 7 Playbook per app Capacitor

Alle 16:00, un aggiornamento del web-layer arriva in produzione. In pochi minuti, i report dei crash aumentano, arrivano i ticket di supporto e il team scopre che il nuovo bundle JavaScript fallisce solo su un subset di dispositivi. Aspettare la revisione di App Store o Google Play non è un'opzione, ma ripristinare un file precedente non basta se sono cambiate anche configurazioni, API, feature flag o dati salvati. Un buon esempio di rollback plan deve indicare all'operatore cosa attiva la risposta, quale versione ripristinare, come verificare il ripristino e quando il rollback di code potrebbe peggiorare l'incidente.

I sette playbook qui sotto associano le azioni di rollback a specifici tipi di errore in app Capacitor ed Electron, inclusi i rilasci distribuiti tramite canali Capgo. Usali come modelli di runbook, sostituendo poi i trigger di esempio con i baseline del tuo monitoraggio di crash, business e integrità dei dati.

Indice dei contenuti

• 1. Rollback automatico al rilevamento di crash
  • Trigger, azione e modalità di errore
• 2. Rollback di Differential Update con cronologia versioni
• 3. Rollout graduale con rollback automatico su calo metriche
• 4. Rollback di sola configurazione con Feature Flags
  • Eseguire il rollback dei flag come playbook strutturato
• 5. Rollback Canary con consenso utente e override manuale
• 6. Rollback di migrazione database con versionamento schema
• 7. Rollback basato su incident con observability e post-mortem
• 7 esempi di Rollback Plan a confronto
• Trasforma questi esempi in un tuo Runbook

1. Rollback automatico al rilevamento di crash

Il rollback automatico è la prima risposta corretta quando un nuovo web bundle causa un evidente fallimento all'avvio, un'eccezione JavaScript, un errore di un plugin nativo o un pattern di crash assente nella release precedente. Il trigger deve essere leggibile dalle macchine e collegato a una versione, un canale, un gruppo di dispositivi e una finestra di osservazione. Un release controller può sospendere la distribuzione e ripristinare l'ultimo bundle funzionante senza attendere che un ingegnere noti l'anomalia sulla dashboard.

Per un'app Capacitor, monitora più dei semplici crash nativi. Traccia se l'applicazione si avvia, se la web view carica, se notifyAppReady() si completa, se i plugin critici si inizializzano e se il primo user flow ha successo. I team Electron dovrebbero aggiungere i fallimenti del renderer-process, le eccezioni del main-process, i fallimenti dell'installazione degli update e le chiamate IPC fallite.

Regola pratica: Il rollback automatico deve prima interrompere l'esposizione e poi ripristinare il servizio. Non deve tentare di diagnosticare la root cause mentre gli utenti stanno ancora ricevendo il bundle sospetto.

Un trigger pratico potrebbe essere un aumento costante di crash o di readiness check falliti rispetto alla baseline della release. Non copiare una soglia da un'altra app. Imposta un limite conservativo per la produzione, validalo rispetto alle normali variazioni di dispositivi e OS, e richiedi un numero sufficiente di osservazioni per evitare di reagire a un singolo dispositivo isolato.

Trigger, azione e modalità di fallimento

• Trigger: Segnali di crash, startup, readiness o plugin nativi superano la soglia di guardia per il canale interessato.
• Azione: Blocca l'espansione del canale, segna il bundle come unhealthy, ridistribuisci il precedente bundle firmato e verifica l'avvio e i flussi critici.
• Trade-off: Il ripristino è rapido, ma un trigger troppo sensibile può annullare un rilascio funzionante a causa di problemi non correlati al dispositivo o al backend.
• Modalità di errore: Il bundle precedente dipende da una API o configurazione modificata, quindi l'app si avvia ma fallisce in seguito. Mantieni i controlli di compatibilità nella health gate.

Per la diagnosi per singolo dispositivo e la correlazione dei crash, usa questa guida per connettere Firebase Crashlytics con le app Capacitor. Testa l'intero percorso in un canale di staging, inclusi rilevamento, freeze del canale, ridistribuzione, download del client, attivazione e conferma che la vecchia versione sia ancora utilizzabile.

2. Rollback tramite Differential Update con cronologia versioni

Un rollback differenziale è ideale per errori isolati a un foglio di stile, un asset, un valore di configurazione o un modulo JavaScript. L'updater trasferisce solo i file diversi tra il rilascio attivo e il target noto come funzionante, riducendo il download per gli utenti con connessioni instabili. Il target deve comunque ricostruire un rilascio completo.

Il trigger è un errore confermato a livello di file che non richiede modifiche al runtime nativo. Prima di agire, confronta i manifest attivi e precedenti, controlla la versione di Capacitor o del runtime Electron e conferma che il canale interessato abbia un bundle firmato compatibile. Se l'errore supera questo limite, distribuisci l'intero bundle precedente invece di tentare una riparazione solo sui file.

La consegna differenziale non è un ripristino parziale. Non combinare mai file arbitrari provenienti da diversi release. Conserva manifest immutabili, valida checksum e firme, mantieni l'artifact completo precedente e registra la versione attiva nella cronologia del canale. Un mismatch tra bundle JavaScript e plugin nativo può far avviare l'app, ma causare il fallimento di un flusso critico in seguito.

di Capgo cronologia versioni app aiuta gli operatori a individuare una build funzionante prima del redeployment. Per ogni release, registra l'identifier del bundle, la versione del runtime nativo, il canale Capgo, la revisione della configurazione e le note di migrazione.

Usa questo runbook:

1. Conferma che l'errore sia limitato a web asset, configurazione o code.
2. Blocca il canale interessato per evitare che altri dispositivi ricevano la versione sospetta.
3. Seleziona l'ultimo bundle firmato compatibile, non solo il file precedente più vicino.
4. Genera un aggiornamento differenziale solo se client e manifest supportano una ricostruzione sicura.
5. Test di avvio, controlli di integrità, compatibilità con API e flusso utente interessato.
6. Monitora download, attivazione e completamento del rollback su client Capacitor ed Electron.

Errori di ricostruzione, mismatch del checksum, dipendenze native incompatibili o loop di attivazione sono modalità di fallimento. Interrompi la delivery differenziale e ridistribuisci il bundle completo conservato. La cronologia delle versioni indica cosa è cambiato e quale release può superare il limite di compatibilità in sicurezza. Non sostituisce gli artifact di rollback testati o le note di migrazione.

3. Rollout graduale con rollback automatico in caso di degrado delle metriche

Una release può superare i controlli di startup e danneggiare comunque un workflow critico. Per un rollout graduale, separa i cohort beta, staging, produzione o clienti in canali Capgo distinti. Promuovi un bundle firmato alla volta e mantieni disponibile la versione compatibile precedente per ogni canale. Questo limita l'esposizione preservando un percorso di recovery diretto per i client Capacitor ed Electron.

Imposta il release gate prima della promozione. Per un cambio nel checkout, monitora i pagamenti completati invece dei soli crash. Per la messaggistica, controlla la latenza e l'invio andato a buon fine. Per la sincronizzazione sanitaria, valida l'integrità dei record. Confronta ogni segnale con il baseline per lo stesso pubblico, mix di dispositivi e canale. Una release è sana solo quando l'azione critica viene completata correttamente.

Usa questa sequenza durante la promozione:

1. Assegna un responsabile per revisionare i segnali tecnici e di business.
2. Osserva il cohort definito per il periodo concordato.
3. Interrompi la promozione non appena una metrica monitorata supera la soglia approvata.
4. Blocca il canale Capgo interessato e conserva il release ID, le versioni client, la configurazione e le metriche.
5. Redeploy dell'ultimo bundle compatibile su quella cohort.
6. Verifica l'avvio, l'attivazione dell'update e il workflow interessato su dispositivi Capacitor ed Electron rappresentativi.
7. Riprendi la promozione solo dopo che il proprietario ha confermato il ripristino.

L'oggetto guida ai rollout graduali per i Capacitor live updates fornisce il contesto di deployment per i rilasci basati su canali. Il rollback automatico deve avvenire solo quando metriche e soglie sono inequivocabili. Errori di pagamento, privacy, sicurezza o integrità dei dati possono giustificare un'azione immediata anche senza certezza statistica.

Il principale rischio è un dashboard troppo limitato. La salute tecnica può risultare normale mentre un business outcome peggiora, e condizioni rare di device, account o rete potrebbero non emergere nella prima cohort. Documenta queste lacune nel runbook prima del prossimo rilascio.

4. Rollback della sola configurazione con Feature Flag

Un rollback della configurazione è ideale per errori isolati a una singola funzionalità. Mantieni installato il nuovo bundle Capacitor o Electron, quindi disattiva il percorso rischioso tramite un flag remoto per il canale Capgo o l'audience interessata. L'app può ripristinare la logica di raccomandazione, una variante dell'interfaccia, la sincronizzazione opzionale, lo storage sperimentale o un altro comportamento protetto senza sostituire code non correlati.

Il fallback deve già esistere. Verifica che resti compatibile con l'attuale API e il modello dati, assegna un owner e registra lo scope del flag e il default di emergenza prima del rilascio. Rimuovere il vecchio path e aggiungere un flag dopo un incidente non lascia nulla da attivare.

Esegui il rollback del flag come playbook circoscritto

1. Trigger: Un errore specifico di una feature, un workflow fallito, problemi di privacy, di batteria o una regressione di business superano la soglia concordata dal team.
2. Azione: Disabilita il flag per il canale Capgo o l'audience interessata. Conferma che i client ricevano la modifica, quindi testa il fallback su dispositivi Capacitor ed Electron rappresentativi.
3. Verifica: Controlla lo stato del flag attivo, gli eventi rilevanti, il comportamento all'avvio e il workflow interessato. Mantieni il nuovo bundle in uso mentre il team isola il problema.
4. Trade-off: La modifica è rapida e mirata, ma non può riparare una dipendenza condivisa, un code nativo incompatibile o dati corrotti.
5. Modalità di errore: L'update potrebbe non arrivare, essere ignorato all'avvio o rimanere in cache. Logga lo stato del flag con ogni evento rilevante e definisci la scadenza della cache.

Usa il valore guida all'implementazione dei feature flag per strutturare questo controllo in un workflow Capgo. Mantieni un default locale di emergenza per le feature critiche. Se la configurazione non è recuperabile, applica il fail closed. Le feature sensibili alla sicurezza e alla privacy dovrebbero disabilitare l'accesso durante un outage del control-plane invece di preservarlo.

5. Canary Rollback con consenso utente e override manuale

Un canary release può sembrare sano nella telemetria pur fallendo per un account enterprise, un ruolo utente o un'integrazione. Fornisci a quel gruppo un fallback chiaro e un modo per segnalare il problema. Il loro feedback può far emergere fallimenti di workflow o usabilità che le metriche aggregate non rilevano.

Usa controlli separati per utenti e operatori. L'azione lato utente deve essere disponibile al di fuori del workflow interrotto, spiegare cosa sta revertendo e raccogliere il bundle attivo, la versione dell'app native, il canale Capgo, il dispositivo e il timestamp. Per le app Capacitor, verifica il precedente web bundle rispetto alla native shell installata. Per Electron, conferma che il fallback rimanga compatibile con il runtime desktop pacchettizzato.

Imposta il trigger canary prima del rilascio:

• Trigger: Blocca il canale dopo ripetuti opt-out da un segmento, report raggruppati o una metrica tecnica che supera la soglia concordata.
• Azione utente: Mostra la scelta di fallback, registra il consenso e il contesto diagnostico, quindi riporta l'utente al bundle precedente compatibile.
• Azione dell'operatore: Sospendi ulteriori esposizioni, esamina i report e reindirizza il canale canary alla build stabile. Tieni disponibile un override manuale quando il control plane o la UI client non sono disponibili.
• Trade-off: Il consenso migliora la trasparenza e permette di individuare i problemi precocemente, ma versioni miste aumentano l'impegno del supporto e complicano i confronti.
• Modalità di errore: Un utente potrebbe effettuare il rollback senza inviare il contesto, oppure il vecchio client potrebbe non funzionare con un backend modificato. Tratta le best practice per il consenso utente sugli aggiornamenti OTA come parte della strategia di comunicazione e opt-out, garantendo la compatibilità con il server o un rollback controllato delle funzionalità.

Non presentare questo rollback come una soluzione per l'incompatibilità lato server. Se il contratto del backend è cambiato, ripristina prima la compatibilità o mantieni disabilitato il workflow interessato.

6. Rollback della migrazione del database con versionamento dello schema

Un rollback del bundle non può risolvere uno schema incompatibile. Un client Capacitor o Electron può tornare alla precedente code, mentre il API o il database locale si aspettano ancora nuovi campi, tipi modificati o dati parzialmente migrati. Il risultato può essere letture fallite, scritture rifiutate o record errati.

Tratta la migrazione come un rilascio a sé stante con un piano di recovery. Inizia con una fase di espansione: aggiungi campi o tabelle compatibili senza rimuovere la vecchia rappresentazione. Distribuisci code in grado di leggere e scrivere entrambi i formati, quindi migra i record esistenti con validazione. Gestisci il passaggio del traffico in modo deliberato. Rimuovi le strutture legacy solo quando il client precedente non sarà più necessario. Questo permette un rollback del canale Capgo mentre il nuovo schema rimane distribuito.

La recensione su migrazioni database sicure per il rollback copre le migrazioni transazionali, gli schemi backward-compatible e il deployment separato di database e applicazione. Applica questi controlli ai record di pagamento, agli ordini, alle informazioni dei pazienti e ad altri dati che non possono essere ricreati in sicurezza.

Definisci il piano di recovery prima del rilascio:

• Rollback dell'applicazione: Ripristina il precedente bundle Capacitor o il pacchetto Electron solo dopo aver confermato che sia in grado di leggere lo schema attuale.
• Rollback delle feature: Disabilita il nuovo percorso di scrittura o la feature flag, mantenendo però le modifiche compatibili allo schema.
• Recovery della migrazione: Interrompi le scritture interessate, ispeziona i record ed esegui una procedura di forward-fix o di recovery già verificata.
• Ripristino dei dati: Usa backup o point-in-time recovery quando il rollback di code non può ripristinare la correttezza dei dati.

Tieni sotto controllo gli script di forward e recovery. Testali con dati simili a quelli di produzione e usa transazioni o savepoint dove supportati. Non generare SQL di rollback distruttivi durante un incidente. Definisci le condizioni di successo per la salute dell'app, la validità dei dati e la compatibilità in scrittura, assegnando un responsabile per ogni decisione. Un piano di migrazione non testato in staging non è un esempio di rollback plan affidabile.

7. Rollback basato su incidenti con Observability automatizzata e Post-Mortem

Un canale Capgo può mostrare un rollout sano mentre una specifica coorte Capacitor o Electron fallisce dopo il lancio. Definisci il trigger dell'incidente prima del rilascio, come un segnale di crash persistente, un readiness check fallito, un flusso API interrotto o un errore confermato di integrità dei dati. Al verificarsi dell'alert, blocca l'espansione del canale e registra il bundle attivo, la versione della native app, il canale, lo stato del rollout, la coorte interessata, la categoria dell'errore e i timestamp. Raccogli queste prove prima di modificare lo stato del deployment.

Linee guida DORA sulle metriche di deployment e recovery inquadra il rollback sia come segnale di change-failure che come evento di recovery. Salva l'identifier del rilascio e il risultato del rollback, quindi confronta il tempo detection-to-restoration, le sessioni o i dispositivi interessati e i tassi di errore post-recovery. Queste misure indicano se il bundle ripristinato ha effettivamente risolto il problema.

Gestisci l'incidente come una sequenza breve e registrata:

1. Trigger: Conferma l'alert incrociando crash, readiness, API, segnali di business o dati.
2. Freeze: Blocca l'espansione del canale e disabilita la feature flag se limita l'impatto meglio di un rollback completo.
3. Preserve: Salva log, trace, cronologia versioni, stato di adozione e dettagli sul segmento interessato.
4. Rollback: Redeploy l'ultimo bundle compatibile per Capacitor o Electron, verificando la compatibilità con la versione native.
5. Check: Testa l'avvio e i flussi critici, poi conferma che il segnale di errore stia diminuendo.
6. Review: Registra la causa, il mancato rilevamento, la decisione e la modifica al runbook.

Un rollback fallito è di per sé un trigger. Passa al precedente canale stabile o a un deployment manuale se la versione ripristinata crasha, non parte o riproduce lo stesso errore API. Usa questo Forge Reliability root cause guide per strutturare l'indagine. Conduci il post-mortem senza colpevolizzare nessuno finché le prove sono disponibili, assegna un responsabile a ogni azione correttiva e testa il nuovo readiness check o il guardrail del canale.

7 esempi di Rollback Plan a confronto

Trasforma questi esempi di Rollback Plan nel tuo Runbook

Non scegliere un unico meccanismo di rollback per ogni incidente. Inizia dall'azione più mirata e sicura. Se un feature flag può disabilitare il percorso difettoso preservando l'integrità dei dati, usalo per primo. Se il rilascio stesso è instabile, ferma l'espansione del canale e usa controlli su canali staged con gate automatizzati per crash e readiness. Se il guasto influisce su code condivisi, configurazioni o API incompatibili, ripristina l'ultimo bundle compatibile e verifica l'intero user flow.

La decisione più difficile riguarda i dati. Un rollback del bundle non inverte una migrazione dello schema, una scrittura parziale o un cambio di comportamento lato server. In questi casi, blocca le scritture rischiose, coinvolgi il data owner e segui la procedura di migrazione sicura, invece di dare per scontato che il client precedente sia automaticamente più sicuro. Il fallimento di Knight Capital nel 2012 illustra perché ripristinare un binario precedente non basti: un server manteneva una funzionalità legacy dormiente, un flag riutilizzato l'ha attivata e il rollback tentato ha lasciato il comportamento problematico attivo nell'ambiente. L'incidente ha causato circa 397 milioni di esecuzioni errate di azioni, una posizione teorica di circa $ 7 miliardi, e una perdita iniziale pre-tasse riportata di circa $440 milioni, successivamente posizionati vicino a $460 milioni in report più ampi, come documentato in questo caso del rollback fallito di Knight Capital.

Il deployment di Storm di Spotify offre un altro principio utile per i sistemi stateful. Mantenere disponibili due versioni complete della topologia, preservare le posizioni dei consumer e usare un'attivazione reversibile permette agli operatori di ripristinare la versione precedente senza perdere lo stream, come descritto nel caso del deployment Apache Storm di SpotifyUn design Capgo analogo consiste nel mantenere il precedente bundle firmato, preservare i health gate specifici per versione e confermare la compatibilità prima di rimuovere la vecchia release.

Trasforma queste idee in un breve albero decisionale:

• Fallimento di una feature specifica: Disabilita la feature flag, verifica il fallback e investiga.
• Instabilità del rilascio: Blocca il canale, ridistribuisci l'ultimo bundle compatibile e monitora il ripristino.
• Incertezza specifica per segmento: Interrompi la promozione e usa il feedback canary insieme all'override manuale.
• Rischio schema o dati: Non fare un rollback cieco di code. Blocca le modifiche ed esegui il piano di migrazione o di recupero dati.
• Causa non chiara: Raccogli prima le prove, limita l'esposizione e scegli l'azione reversibile più mirata.

Scegli un playbook oggi stesso. Definisci trigger, responsabile, il comando di rollback esatto o l'azione sulla dashboard, i passaggi di verifica e il percorso di escalation. Testalo in un canale di staging prima del prossimo rilascio in produzione, simulando un update fallito, un segnale di readiness non valido, un rollback di configurazione e un controllo di compatibilità. I team si riprendono più velocemente quando il rollback è un'operazione già testata, non un paragrafo scritto dopo l'incidente.

Capgo fornisce live update firmati per app CapacitorJS ed Electron, con canali mirati, cronologia delle versioni, log per singolo dispositivo, metriche di adozione e di errore, delivery differenziale e protezione con rollback automatico. Usa Capgo per trasformare l'esempio di piano di rollback adatto alla tua app in un workflow di rilascio e recovery testato.