주요 변경 사항

이 문서는 버전별 채널을 사용하여 앱의 breaking changes를 처리하는 방법을 설명합니다. 이 방식을 통해 앱의 여러 버전을 유지하면서도 사용자가 호환 가능한 업데이트를 받을 수 있도록 보장할 수 있습니다.

예시 시나리오

다음과 같은 상황을 가정해 보겠습니다:

• 앱 버전 1.2.3 (이전 버전) - production 채널 사용
• 앱 버전 2.0.0 (breaking changes가 포함된 새 버전) - v2 채널 사용
• Live update 1.2.4 (1.2.3과 호환됨)
• Live update 2.0.1 (2.0.0과 호환)

전략: 메이저 버전에는 항상 defaultChannel 사용

권장 방식: 각 메이저 버전마다 defaultChannel 를 설정하세요. 이렇게 하면 동적 채널 할당에 의존하지 않고도 특정 사용자 그룹에 항상 업데이트를 푸시할 수 있습니다.

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

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

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

팁

이 방식의 장점:

• 업데이트를 받는 사용자를 항상 직접 제어할 수 있습니다
• 동적 채널 전환 불필요 앱 code 내에서
• 명확한 분리 서로 다른 앱 버전 간의
• 유연성 특정 버전 그룹에 업데이트 푸시 가능

1. 새 버전을 위한 채널 생성

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

2. 버전 2.0.0을 위한 Capacitor 설정 업데이트

앱 스토어용 2.0.0 버전을 빌드하기 전에 Capacitor 설정을 업데이트하세요:

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;

참고

1.x 버전의 경우: 처음에 defaultChannel 를 설정하지 않았다면, 1.x 버전 사용자는 production 채널을 사용 중입니다. 향후 메이저 버전에서는 항상 v3, v4, 등.

3. 별도의 Code 브랜치 관리

앱 버전 간 호환성을 유지하려면 별도의 git 브랜치를 생성하세요:

# 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

주의: 네이티브 code/API가 없는 구버전 앱에 JavaScript bundle을 푸시하지 마세요. 반드시 적절한 브랜치에서 업데이트를 빌드해야 합니다:

• v1-maintenance 브랜치: 1.x 앱 업데이트용 (production 채널)
• main 브랜치: 2.x 앱 업데이트용 (v2 채널)

4. 각 채널에 Bundle 업로드하기

# 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. 셀프 할당 활성화

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

6. App Store 배포

버전 2.0.0을 빌드하여 App Store에 배포하세요. 이 버전을 다운로드하는 모든 사용자(신규 사용자 및 기존 업그레이드 사용자 포함)는 앱 번들에 설정된 대로 자동으로 v2 채널을 사용하게 됩니다.

참고

code 변경 사항이 필요 없습니다! 도입 버전 defaultChannel: 'v2' 앱 스토어 버전과 함께 번들링되므로, 2.0.0 버전을 다운로드하는 모든 사용자는 자동으로 올바른 채널을 사용하게 됩니다.

향후 버전으로의 확장

더 많은 breaking changes가 포함된 3.0.0 버전을 출시할 경우:

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

이제 모든 버전에 업데이트를 푸시할 수 있습니다:

• production channel → Version 1.x 사용자
• v2 channel → Version 2.x 사용자
• v3 channel → Version 3.x 사용자

7. 정리 (마이그레이션 후)

모든 사용자가 2.x 버전으로 마이그레이션을 완료하면 (약 3~4개월 소요):

1. 제거하세요 defaultChannel Capacitor 설정에서
2. v2 채널을 삭제하세요:

npx @capgo/cli channel delete v2

3. v1-maintenance 브랜치를 삭제하세요:

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

팁

이 방식을 통해 사용자는 자신의 앱 버전과 호환되는 업데이트만 받게 됩니다.

배포 전 항상 각 채널에서 업데이트를 철저히 테스트하세요.

참고

Capgo에서 v2 채널을 삭제해도 안전합니다. 일부 사용자가 채널 오버라이드를 사용 중이더라도, 자동으로 production 채널의 업데이트를 받게 됩니다.

Version 1.x 업데이트 유지 관리

Version 1.x와 호환되는 업데이트를 보내려면:

1. v1-maintenance 브랜치로 전환하세요:

git checkout v1-maintenance

2. 변경 사항을 적용하고 커밋하세요:

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

3. 프로덕션 채널 빌드 및 업로드:

npx @capgo/cli bundle upload --channel production

팁

v1-maintenance 브랜치는 1.x 버전과 호환되는 버그 수정 사항으로 최신 상태를 유지하되, main 브랜치의 breaking changes는 절대 머지하지 마세요.

Breaking Changes 다음 내용 보기

사용 중인 경우 주요 변경 사항 채널 라우팅과 단계적 롤아웃을 계획하려면, 이를 다음 항목과 연결하세요 채널 Channels의 구현 세부 사항은, 채널 Channels의 구현 세부 사항은, 채널 Channels의 구현 세부 사항은, Beta Testing 솔루션 Beta Testing 솔루션의 제품 워크플로우는, Version Targeting 솔루션 Version Targeting 솔루션의 제품 워크플로우를 확인하세요.