SDK Version Policy

SDK 버전 정책

정본

SDK	버전 정본	배포 식별자
TypeScript	packages/sdk-ts/package.json과 src/version.ts	tag sdk-ts-vX.Y.Z, GitHub Packages @seorilabs/platform-sdk@X.Y.Z, 통합 릴리스의 seorilabs-platform-sdk-X.Y.Z.tgz
GDScript	sdk-gdscript/VERSION	tag vX.Y.Z, 통합 릴리스의 seorilabs-platform-gdscript-X.Y.Z.tar.gz + .sha256, vendored SOURCE VERSION CHECKSUM

통합 릴리스 vX.Y.Z에는 두 SDK 산출물과 platform-release.json 매니페스트가 함께 붙습니다. 매니페스트는 각 산출물의 sha256, source SHA, 계약 revision과 분류 (implementation-only / contract-additive)를 기록합니다.

Wiki의 버전 표기와 코드가 다르면 코드와 tag/release readback을 우선하고 Wiki를 즉시 수정합니다.

상태 용어

• 현재 권장: 신규 앱이 선택해야 하는 최신 검증 버전
• 이전 버전: 이미 탑재한 앱을 위해 문서를 보존하지만 신규 통합에는 권장하지 않음
• 철회: 자산이 발행되지 않았거나 결함이 확인된 버전. 사용 금지 (v0.6.5)
• 공개되지 않음: tag/release 근거가 없는 버전 (TypeScript 0.2.x)

현재 TypeScript 권장은 0.4.0, GDScript 권장은 0.6.7입니다. 별도 장기지원 기간을 약속하지 않으며, 서버 /v1 계약은 additive 변경과 미지 필드 허용으로 이미 배포된 앱을 깨지 않게 유지합니다.

TypeScript 발행 게이트

1. package.json과 SDK_VERSION을 같은 버전으로 맞춥니다.
2. pnpm test, pnpm typecheck, pnpm build, release contract 테스트를 통과합니다.
3. npm pack 산출물을 빈 환경에 설치해 import와 version을 확인합니다.
4. sdk-ts-vX.Y.Z tag로 publish workflow를 실행합니다.
5. GitHub Packages에서 정확한 버전을 readback합니다.
6. TypeScript-SDK-X.Y.Z Wiki 페이지와 Home, Sidebar를 갱신합니다.

배포 workflow 성공과 패키지 readback은 별도 gate입니다. 둘 다 확인해야 게시 완료입니다.

GDScript 발행 게이트

1. SDK 코드와 VERSION을 함께 변경합니다.
2. scripts/sdk_gdscript_checksum.sh --write로 checksum을 갱신하고 같은 커밋에 넣습니다.
3. conformance, smoke, adapter probe와 SCRIPT ERROR, ERROR: 로그를 확인합니다.
4. main의 정확한 SHA에 vX.Y.Z tag를 만들면 publish workflow가 tarball, .sha256, platform-release.json을 발행합니다. 같은 SHA로 두 번 만들어 byte-identical인지 확인합니다.
5. 발행된 asset URL을 SOURCE에 고정하는 후속 커밋을 넣습니다.
6. GDScript 버전 이력에 tag, source SHA, 변경 내용을 추가합니다.

실패한 릴리스는 덮어쓰지 않고 철회로 표시한 채 다음 patch로 넘어갑니다 (0.6.5 → 0.6.6).

GDScript는 package registry가 없으므로 VERSION 문자열만으로 동일 배포본을 증명할 수 없습니다. tarball sha256과 CHECKSUM(tree checksum)을 함께 대조합니다.

호환성 원칙

• 응답의 미지 필드는 무시합니다. 키 개수를 세지 않습니다.
• 공개 /v1 필드 제거·의미 변경은 하지 않습니다. breaking change는 /v2입니다.
• IAP 쓰기와 광고 claim은 일반 네트워크 오류에서 자동 반복하지 않습니다.
• Remote Config 실패는 열린 기본값을 사용합니다.
• Presence는 opt-in이며 실패를 호출자에게 전파하거나 outbox/replay하지 않습니다.
• 두 SDK의 행동 규약은 spec/conformance/*.json이 정본이고 양쪽 CI가 같이 게이트로 겁니다.