Breaking changes

Cette documentation explique comment gérer les breaking changes dans votre application à l'aide de canaux versionnés. Cette approche vous permet de maintenir différentes versions de votre application tout en garantissant que les utilisateurs reçoivent des mises à jour compatibles.

Exemple de scénario

Supposons que vous ayez :

• Version de l'app 1.2.3 (ancienne version) – utilise le canal production
• Version de l'app 2.0.0 (nouvelle version avec breaking changes) – utilise le canal v2
• Live update 1.2.4 (compatible avec 1.2.3)
• Live update 2.0.1 (compatible avec 2.0.0)

Stratégie : utilisez toujours defaultChannel pour les versions majeures

Approche recommandée : Définissez un defaultChannel pour chaque version majeure. Cela vous permet de toujours envoyer des mises à jour à des groupes d’utilisateurs spécifiques, sans dépendre de l’attribution dynamique des canaux.

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

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

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

Astuce

Avantages de cette approche :

• Avoir toujours le contrôle sur les utilisateurs qui reçoivent les mises à jour
• Aucun changement de canal dynamique nécessaire dans votre application code
• Séparation claire entre les différentes versions de l'app
• Flexibilité pour envoyer des mises à jour à un groupe de versions spécifique

1. Créer un canal pour la nouvelle version

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

2. Mettre à jour la config Capacitor pour la version 2.0.0

Mettez à jour votre configuration Capacitor avant de compiler la version 2.0.0 pour le 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;

Remarque

Pour la version 1.x : Si vous n’avez pas défini de defaultChannel initialement, les utilisateurs de la version 1.x sont sur production canal. Pour les futures versions majeures, définissez toujours un canal spécifique comme v3, v4, etc.

3. Gérer des branches Code distinctes

Créez des branches git distinctes pour maintenir la compatibilité entre les versions de l'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

Critique : N'envoyez jamais de bundles JavaScript vers des apps plus anciennes qui attendent des code/API natives qu'elles n'ont pas. Buildez toujours vos mises à jour depuis la branche appropriée :

• branche v1-maintenance: Pour les mises à jour des apps 1.x (canal production)
• branche main: Pour les mises à jour des apps 2.x (canal v2)

4. Envoyer les bundles vers les canaux respectifs

# 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. Activer l'auto-assignation

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

6. Déployer sur l'App Store

Compilez et déployez la version 2.0.0 sur le store. Tous les utilisateurs qui téléchargent cette version (nouveaux utilisateurs ou utilisateurs existants qui mettent à jour) utiliseront automatiquement le canal v2, car il est configuré dans le bundle de l'app.

Remarque

Aucun changement code nécessaire ! Depuis defaultChannel: 'v2' est bundlé avec la version du store, tous les utilisateurs qui téléchargent la version 2.0.0 utiliseront automatiquement le bon canal.

Évoluer vers les versions futures

Lorsque vous publiez la version 3.0.0 avec plus de breaking changes :

# 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
    }
  }
};

Now you can push updates to any version:

• production canal → utilisateurs de la version 1.x
• v2 canal → utilisateurs de la version 2.x
• v3 canal → utilisateurs de la version 3.x

7. Nettoyage (après la migration)

Une fois que tous les utilisateurs ont migré vers la version 2.x (comptez 3 à 4 mois) :

1. Supprimer defaultChannel de votre config Capacitor
2. Supprimez le canal v2 :

npx @capgo/cli channel delete v2

3. Supprimez la branche v1-maintenance :

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

Astuce

Cette approche garantit que les utilisateurs ne reçoivent que des mises à jour compatibles avec leur version de l'app

Testez toujours minutieusement les mises à jour dans chaque canal avant le déploiement

Remarque

Vous pouvez supprimer sans risque le canal v2 dans Capgo, même si certains utilisateurs ont encore l'override de canal. Ils recevront alors automatiquement les mises à jour du canal de production.

Maintenir les mises à jour de la version 1.x

Pour envoyer des mises à jour compatibles avec la version 1.x :

1. Basculez sur la branche v1-maintenance :

git checkout v1-maintenance

2. Faites vos modifications et commitez :

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

3. Compiler et envoyer vers le canal de production :

npx @capgo/cli bundle upload --channel production

Astuce

Maintenez votre branche v1-maintenance à jour avec des correctifs compatibles avec la version 1.x, mais ne fusionnez jamais de breaking changes provenant de main

Continuer après les breaking changes

Si vous utilisez Breaking changes pour planifier le routage des canaux et le déploiement progressif, connectez-l’avec Canaux pour les détails d'implémentation des canaux, Canaux pour les détails d'implémentation des canaux, Canaux pour les détails d'implémentation des canaux, Solution de bêta-test pour le workflow produit de la Solution de bêta-test, et Solution de ciblage de version pour le workflow produit de la Solution de ciblage de version.