본문 바로가기

Capgo Semver Tester

version_build로 전송된 Native Baseline과 채널 정책 간의 호환성을 확인합니다.

config 또는 native app metadata에서 version_build로 Capgo에 전달되는 native version입니다.

해당 채널에 할당된 bundle version입니다.

비교할 두 개의 semantic version을 입력하세요

"Native Baseline Version"의 의미

Native Baseline Version은 디바이스가 업데이트 서버에 번들을 요청할 때 Capgo로 전송되는 version_build 네이티브 앱 버전입니다. Capacitor 앱에서 이 값은 다음에서 가져올 수 있습니다: CapacitorUpdater.version 에서 capacitor.config.*. 해당 설정이 없으면 플러그인은 iOS 또는 Android의 네이티브 앱 버전을 사용합니다. 빌드 시 해당 값을 config나 네이티브 메타데이터에 복사하지 않았다면, package.json 이를 앱 버전으로 간주해서는 안 됩니다.

Capgo는 현재 설치된 번들을 확인하기 위해 여전히 version_name 를 사용합니다. 다음과 같은 Channel semver 정책은 major, minor, 그리고 patch 원격 번들을 다음 항목과 비교합니다: version_build.

Capacitor 설정

설정 CapacitorUpdater.version 앱에서 명시한 버전 하나를 전송하고 싶을 때.

장점: iOS와 Android 빌드 간 버전을 동일하게 유지하기 쉽습니다.

단점: 네이티브 릴리스 전에 업데이트하는 걸 잊으면 오래된 설정 때문에 잘못된 버전이 보고될 수 있습니다.

네이티브 앱 버전

iOS와 같은 플랫폼 버전을 사용하세요 CFBundleShortVersionString 또는 Android versionName.

장점: TestFlight, App Store, Play Store 또는 내부 테스트에서 사용자가 설치한 바이너리와 일치합니다.

단점: 변경 시 Native Build가 필요하며, 릴리스 설정이 어긋날 경우 플랫폼마다 다를 수 있습니다.

Bundle 타겟팅

원격 bundle 버전, 채널 semver 규칙 또는 다음과 같은 메타데이터 upload 제약 사항을 비교해 보세요: --min-update-version. 채널에서 반드시 사용해야 합니다 --disable-auto-update metadata.

장점: 구버전 앱 바이너리에 더 높은 버전의 native code가 필요한 JavaScript를 전송하는 것을 방지합니다.

단점: 규칙이 너무 엄격하면 채널이나 bundle 메타데이터를 조정하기 전까지 유효한 업데이트가 차단될 수 있습니다.

이 테스터를 사용하려면 기기가 전송하는 native baseline을 version_build로 입력한 후, Capgo가 배포하려는 원격 bundle 버전과 비교해 보세요.

Capgo가 Semantic Versioning을 사용하는 이유

Semantic Versioning 소프트웨어 개발에서 가장 널리 쓰이는 버전 관리 표준입니다. semver를 사용하면 Capgo가 Capacitor 앱에 Live Update를 배포할 때 호환성과 안전성을 보장합니다.

semver 표준을 통해 Capgo는 각 업데이트에 포함된 변경 사항을 정확히 파악할 수 있습니다:

  • Patch 업데이트 (1.0.0 → 1.0.1): 버그 수정, 자동 적용 가능
  • Minor 업데이트 (1.0.0 → 1.1.0): 새로운 기능 추가, 하위 호환성 유지
  • Major 업데이트 (1.0.0 → 2.0.0): Breaking changes 발생, Native Build 스토어 출시 필요

이를 통해 Capgo가 호환되지 않는 업데이트를 code에 전송하는 것을 방지하여, 앱 충돌을 막고 안정성을 유지합니다.

유연한 Semver 전략: 기본 버저닝 그 이상

semver는 핵심 형식을 엄격히 따르지만, 팀의 필요에 따라 다음을 사용하여 확장할 수 있습니다: pre-release 식별자 및 빌드 메타데이터:

🏷️ 빌드 메타데이터 (+) - '장식용' 레이어

1.2.0+20240315.142530
배포 추적용 타임스탬프
1.2.0+ui.refresh.dark-mode
디자인 팀용 UI 업데이트 설명
1.2.0+build.4729.commit.a1b2c3d
CI/CD 빌드 번호와 git commit

중요: 빌드 메타데이터는 버전 우선순위에서 무시됩니다 - 1.2.0+anything 같음 1.2.0 Capgo의 업데이트 로직 기준.

🔧 Pre-release 식별자 (-) - 개발 채널

1.3.0-beta.1
Beta 테스트 채널
1.3.0-hotfix.payment
긴급 수정 브랜치
1.3.0-feature.newapi
기능 브랜치 테스트

참고: Pre-release 버전은 우선순위가 낮습니다 - 1.3.0-beta.1 < 1.3.0

🎯 하이브리드 방식 - 두 방식의 장점 결합

1.3.0-rc.1+ui.redesign.20240315
UI 메타데이터와 타임스탬프가 포함된 Release candidate

실무 Semver 활용 사례 및 팀 전략

🚀 스타트업 / 빠른 개발

0.1.0 - 첫 MVP 출시
0.2.0-beta.1 - 신규 기능 테스트
0.2.0+ui.v2 - UI 리디자인 메타데이터
1.0.0 - 프로덕션 준비 완료

1.0 미만 개발 시 0.x.x 사용, 디자인 추적용 메타데이터 활용

🏢 엔터프라이즈 / 규제 준수

2.1.0 → 분기별 릴리스
2.1.1+sec.patch.cve2024 → 추적 가능한 보안 패치
2.2.0-rc.1+audit.ready → 감사 전 릴리스 후보

컴플라이언스 메타데이터를 포함한 엄격한 semver 적용

🎮 게임 / 크리에이티브 앱

1.0.0+season.winter.2024 → 시즌별 콘텐츠
1.1.0+event.halloween → 이벤트 기반 기능
1.2.0+assets.hd.remaster → 에셋 업데이트

콘텐츠 트래킹을 위한 크리에이티브 메타데이터

⚡ Hotfix 전략

1.2.0 → 현재 프로덕션
1.2.1-hotfix.payment → 긴급 버그 수정
1.2.1+urgent.20240315.1430 → 타임스탬프와 함께 배포

테스트용 프리릴리스, 배포 트래킹용 메타데이터

🌍 멀티 플랫폼 전략

1.3.0+ios.optimized → iOS 전용 최적화
1.3.0+android.material3 → Android 디자인 업데이트
1.3.0+web.pwa.ready → PWA 기능

동일 버전, 플랫폼별 메타데이터

🔄 CI/CD 통합

1.4.0-alpha.1+build.123 → 자동 프리릴리스
1.4.0+deploy.staging.456 → 스테이징 배포
1.4.0+prod.final.789 → 프로덕션 배포

배포 메타데이터를 포함한 자동 버전 관리

💡 전문가 팁:
  • 호환성에 영향을 주지 않는 트래킹, 타임스탬프, 또는 부가 정보에는 빌드 메타데이터(+)를 사용하세요
  • 업데이트 우선순위 조정이 필요한 개발 채널에는 프리릴리스 식별자(-)를 사용하세요
  • 최대 유연성을 위해 두 방식을 조합하세요: 1.2.0-beta.1+ui.dark.theme.20240315
  • 참고: Capgo는 semver 우선순위 규칙을 따르므로, 이에 맞춰 채널 전략을 세우세요.

주의: Capgo는 엄격한 semantic versioning을 사용합니다.

npm의 semver 구현 방식과 달리, Capgo은 공식 SemVer 사양을 엄격히 준수합니다. npm의 node-semver는 사양과 다른 알려진 차이점이 있어 예상치 못한 동작이 발생할 수 있습니다.

예를 들어, npm는 다음과 같은 버전을 1.0.0-alpha.1 사양과 다르게 처리합니다. 관련 내용은 보고된 이슈 및 시도된 수정 사항 을(를) 확인하세요. (병합되지 않음)

유효한 Semantic Version

1.0.0 ✓ 표준 릴리스
2.1.3-alpha ✓ 프리릴리스
1.0.0-beta.1 ✓ 번호가 포함된 Pre-release
1.0.0+build.1 ✓ 빌드 메타데이터
1.0.0-rc.1+build.1 ✓ 전체 버전

유효하지 않은 Semantic Version

v1.0.0 ✗ 앞에 'v'를 붙일 수 없음
1.0 ✗ Patch 버전 누락
1.0.0.0 ✗ 버전 형식이 너무 많음
1.0.0- ✗ Pre-release 값이 비어 있음
1.0.0+ ✗ Build metadata 값이 비어 있음

Capgo 업데이트 동작

✓ Minor 전략은 동일한 major.minor 내에서 1.0.0 -> 1.0.1과 같은 patch 변경을 허용합니다.
✓ Patch 전략은 1.0.0 -> 1.0.1을 차단합니다. 1.0.0-beta.1 -> 1.0.0-beta.2와 같은 접미사 변경만 허용합니다.
✗ Major 전략은 네이티브 베이스라인보다 높은 메이저 버전을 가진 번들을 대상으로 합니다 (예: 1.0.0 -> 2.0.0)
⚠ 다운그레이드 방지는 전체 semver 우선순위를 따르므로, 안정 버전인 1.0.0이 1.0.0-beta.2보다 최신 버전으로 간주됩니다

이 도구는 공식적인 Semantic Versioning 규격을 따릅니다 npm의 구현 방식과는 다릅니다.