마이그레이션 및 버전 관리 정책
공개 API는 v1 내에서 호환성을 유지합니다. 호환성 파괴 변경에는 명시적인 정책 검토, 변경 로그 항목, 마이그레이션 경로가 필요합니다.
호환성 약속
- 추가적인 필드와 엔드포인트는
v1내에서 출시될 수 있습니다. - 기존 응답 필드의 의미는
v1내에서 변경되지 않습니다. - 필수 요청 필드는 호환성 계획 없이 기존
v1쓰기에 추가되지 않습니다. - SDK와 MCP 표면은 동일한 OpenAPI 스코프 및 작업 모델에 대해 검사됩니다.
이것이 의미하는 바
- 응답에서 인식되지 않는 새 필드를 허용하세요(이로 인해 실패하지 마세요).
- SDK를 알려진 버전으로 고정하고 신중하게 업그레이드하세요.
- 추가적인 변경 사항은 변경 로그를 주시하세요.
소스 정책
호환성 파괴 변경 정책은 docs/developer-platform/openapi-breaking-change-policy.md에서 유지 관리되며 계약 검사로 시행됩니다.