Breaking changes

Questa documentazione spiega come gestire i breaking changes nella tua app tramite i canali versionati. Questo approccio ti permette di mantenere diverse versioni della tua app garantendo aggiornamenti compatibili agli utenti.

Scenario di esempio

Supponiamo che tu abbia:

• Versione app 1.2.3 (vecchia versione) - usa il canale production
• Versione app 2.0.0 (nuova versione con breaking changes) - usa il canale v2
• Live update 1.2.4 (compatibile con 1.2.3)
• Live update 2.0.1 (compatibile con 2.0.0)

Strategia: usa sempre defaultChannel per le versioni major

Approccio consigliato: Imposta un defaultChannel per ogni major version. Questo ti permette di inviare aggiornamenti a gruppi di utenti specifici senza dipendere dall'assegnazione dinamica dei canali.

// Version 1.x releases
defaultChannel: 'v1'

// Version 2.x releases
defaultChannel: 'v2'

// Version 3.x releases (future)
defaultChannel: 'v3'

Tip

Vantaggi di questo approccio:

• Controllo totale su quali utenti ricevono gli aggiornamenti
• Nessun cambio dinamico di canale necessario nella tua app code
• Separazione netta tra le diverse versioni dell'app
• Flessibilità per inviare update a gruppi di versioni specifici

1. Crea un canale per la nuova versione

# Create channel for version 2.x
npx @capgo/cli channel add v2

2. Aggiorna la config di Capacitor per la versione 2.0.0

Aggiorna la configurazione di Capacitor prima di buildare la versione 2.0.0 per l'app store:

capacitor.config.ts

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'Example App',
  plugins: {
    CapacitorUpdater: {
      // ... other options
      defaultChannel: 'v2' // All 2.0.0 users will use v2 channel
    }
  }
};

export default config;

Nota

Per la versione 1.x: Se non hai impostato un defaultChannel inizialmente, gli utenti della versione 1.x sono sul production channel. Per le future major version, imposta sempre un channel specifico come v3, v4, ecc.

3. Gestisci branch Code separati

Crea branch git separati per mantenere la compatibilità tra le versioni dell'app:

# Create and maintain a branch for version 1.x updates
git checkout -b v1-maintenance
git push origin v1-maintenance

# Your main branch continues with version 2.x development
git checkout main

Critico: Non pushare mai bundle JavaScript su app più vecchie che si aspettano code/API native non presenti. Genera sempre gli update dal branch corretto:

• branch v1-maintenance: Per gli update alle app 1.x (production channel)
• branch main: Per gli update alle app 2.x (v2 channel)

4. Upload dei bundle sui rispettivi canali

# For 1.x updates: Build from v1-maintenance branch
git checkout v1-maintenance
# Make your 1.x compatible changes here
npx @capgo/cli bundle upload --channel production

# For 2.x updates: Build from main branch
git checkout main
# Make your 2.x changes here
npx @capgo/cli bundle upload --channel v2

5. Abilita il Self-Assignment

# Allow apps to self-assign to v2 channel
npx @capgo/cli channel set v2 --self-assign

6. Deploy su App Store

Builda e deploya la versione 2.0.0 sull'app store. Tutti gli utenti che scaricheranno questa versione (nuovi utenti o utenti esistenti che effettuano l'upgrade) useranno automaticamente il canale v2, poiché è configurato nell'app bundle.

Nota

Nessuna modifica a code richiesta! Da defaultChannel: 'v2' è in bundle con la versione dell'App Store: tutti gli utenti che scaricano la versione 2.0.0 useranno automaticamente il canale corretto.

Scalare verso le versioni future

Quando rilasci la versione 3.0.0 con ulteriori breaking change:

# Create channel for version 3.x
npx @capgo/cli channel add v3

// capacitor.config.ts for version 3.0.0
const config: CapacitorConfig = {
  // ...
  plugins: {
    CapacitorUpdater: {
      defaultChannel: 'v3' // Version 3.x users
    }
  }
};

Ora puoi inviare update a qualsiasi versione:

• production channel → utenti versione 1.x
• v2 channel → utenti versione 2.x
• v3 channel → utenti versione 3.x

7. Pulizia (dopo la migrazione)

Una volta che tutti gli utenti sono migrati alla versione 2.x (circa 3-4 mesi):

1. Rimuovi defaultChannel dalla tua configurazione Capacitor
2. Elimina il canale v2:

npx @capgo/cli channel delete v2

3. Elimina il branch v1-maintenance:

git branch -d v1-maintenance
git push origin --delete v1-maintenance

Tip

Questo approccio garantisce che gli utenti ricevano solo aggiornamenti compatibili con la loro versione dell'app

Testa sempre accuratamente gli aggiornamenti in ogni canale prima del deployment

Nota

Puoi eliminare in sicurezza il canale v2 in Capgo, anche se alcuni utenti hanno ancora l'override del canale. Riceveranno automaticamente gli aggiornamenti dal canale di produzione.

Gestione degli update per la versione 1.x

Per inviare aggiornamenti compatibili con la versione 1.x:

1. Passa al branch v1-maintenance:

git checkout v1-maintenance

2. Applica le modifiche e fai il commit:

# Make 1.x compatible changes
git add .
git commit -m "Fix for v1.x"
git push origin v1-maintenance

3. Build e upload sul canale di produzione:

npx @capgo/cli bundle upload --channel production

Tip

Mantieni aggiornata la branch v1-maintenance con bug fix compatibili con la versione 1.x, ma non merge mai breaking changes dalla branch main

Continua da Breaking Changes

Se stai usando Breaking changes per pianificare il routing dei canali e il rollout graduale, connettilo a Canali per i dettagli di implementazione nei Channels, Canali per i dettagli di implementazione nei Channels, Canali per i dettagli di implementazione nei Channels, Soluzione Beta Testing per il workflow di prodotto nella Soluzione Beta Testing, e Soluzione Version Targeting per il workflow di prodotto nella Soluzione Version Targeting.