Breaking Changes

Diese Dokumentation erklärt, wie Sie Breaking Changes in Ihrer App mit versionierten Channels handhaben. Dieser Ansatz ermöglicht es Ihnen, verschiedene Versionen Ihrer App zu pflegen, während Sie sicherstellen, dass Nutzer kompatible Updates erhalten.

Beispielszenario

Angenommen, Sie haben:

• App-Version 1.2.3 (alte Version) – verwendet den production-Channel
• App-Version 2.0.0 (neue Version mit Breaking Changes) – verwendet den v2-Channel
• Live update 1.2.4 (kompatibel mit 1.2.3)
• Live update 2.0.1 (kompatibel mit 2.0.0)

Strategie: defaultChannel immer für Major-Versionen nutzen

Empfohlener Ansatz: Lege einen defaultChannel für jede Major-Version. So kannst du Updates gezielt an bestimmte Nutzergruppen pushen, ohne auf dynamische Channel-Zuweisung angewiesen zu sein.

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

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

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

Tipp

Vorteile dieses Ansatzes:

• Immer die Kontrolle behalten darüber, welche Nutzer Updates erhalten
• Kein dynamisches Channel-Switching in deiner App code nötig
• Klare Trennung zwischen verschiedenen App-Versionen
• Flexibilität um Updates an jede spezifische Versionsgruppe zu pushen

1. Channel für neue Version erstellen

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

2. Capacitor Config für Version 2.0.0 anpassen

Aktualisiere deine Capacitor-Konfiguration, bevor du Version 2.0.0 für den App Store baust:

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;

Hinweis

Für Version 1.x: Wenn du keinen defaultChannel anfangs festgelegt hast, sind Nutzer von Version 1.x im production Channel. Für zukünftige Major-Versionen setze immer einen spezifischen Channel wie v3, v4, usw.

3. Separate Code Branches verwalten

Erstelle separate Git-Branches, um die Kompatibilität zwischen App-Versionen zu erhalten:

# 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

Wichtig: Schiebt niemals JavaScript-Bundles auf ältere Apps, die native code/APIs erwarten, die sie nicht besitzen. Baut Updates immer vom passenden Branch:

• v1-maintenance-Branch: Für Updates auf 1.x-Apps (Produktionskanal)
• main-Branch: Für Updates auf 2.x-Apps (v2-Kanal)

4. Bundles in die jeweiligen Channels hochladen

# 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. Self-Assignment aktivieren

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

6. Im App Store bereitstellen

Version 2.0.0 bauen und im App Store bereitstellen. Alle Nutzer, die diese Version herunterladen (egal ob neue Nutzer oder bestehende, die upgraden), nutzen automatisch den v2-Channel, da er im App-Bundle konfiguriert ist.

Hinweis

Keine code-Änderungen nötig! Seit defaultChannel: 'v2' ist mit der App-Store-Version gebündelt. Alle Nutzer, die Version 2.0.0 herunterladen, verwenden automatisch den richtigen Channel.

Skalierung für zukünftige Versionen

Wenn Sie Version 3.0.0 mit weiteren Breaking Changes veröffentlichen:

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

Jetzt kannst du Updates an jede Version senden:

• production channel → Nutzer von Version 1.x
• v2 channel → Nutzer von Version 2.x
• v3 channel → Nutzer von Version 3.x

7. Cleanup (nach der Migration)

Sobald alle Nutzer auf Version 2.x migriert sind (rechne mit 3–4 Monaten):

1. Entfernen defaultChannel aus deiner Capacitor Konfiguration
2. Lösche den v2-Channel:

npx @capgo/cli channel delete v2

3. Lösche den v1-maintenance-Branch:

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

Tipp

So wird sichergestellt, dass Nutzer nur Updates erhalten, die mit ihrer App-Version kompatibel sind

Teste Updates vor dem Deployment immer gründlich in jedem Channel

Hinweis

Du kannst den v2-Channel in Capgo sicher löschen, selbst wenn einige Nutzer noch den Channel-Override haben. Sie erhalten dann automatisch Updates aus dem Production-Channel.

Version-1.x-Updates weiter pflegen

Um Updates zu senden, die mit Version 1.x kompatibel sind:

1. Wechsle in den Branch v1-maintenance:

git checkout v1-maintenance

2. Nimm deine Änderungen vor und committe:

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

3. Build erstellen und in den Production-Channel hochladen:

npx @capgo/cli bundle upload --channel production

Tipp

Halte deinen v1-Maintenance-Branch mit Bugfixes auf dem neuesten Stand, die mit Version 1.x kompatibel sind, aber übernehme niemals Breaking Changes von main

Nach Breaking Changes weitermachen

Wenn du es nutzt Breaking Changes um Channel-Routing und Staged Rollout zu planen, verbinde es mit Kanäle für die Implementierungsdetails in Channels, Kanäle für die Implementierungsdetails in Channels, Kanäle für die Implementierungsdetails in Channels, Beta-Testing-Lösung für den Produkt-Workflow in der Beta-Testing-Lösung, und Version-Targeting-Lösung für den Produkt-Workflow in der Version-Targeting-Lösung.