데이터 API 작성기 정책
정책 집합은 호환성이 손상되는 변경, 알림, 릴리스 및 버전 관리와 관련된 데이터 API 작성기를 제어합니다.
버전 관리 및 릴리스
데이터 API 작성기의 컨텍스트에서 릴리스 는 형식으로 식별되는 Major.Minor.Patch 소프트웨어의 게시된 모든 버전을 나타냅니다. 이러한 릴리스는 안정적이고호환성이 손상되는 변경 및 미리 보기의 세 가지 범주로 분류됩니다.
안정적인 릴리스
안정적인 버전의 Data API Builder는 이전 버전과 호환됩니다. 이전 버전과 호환된다는 것은 데이터 API 작성기의 한 버전을 사용하는 모든 코드가 정확성 또는 기존 기능을 유지하기 위해 코드를 변경하지 않고도 안정적인 최신 버전을 채택할 수 있음을 의미합니다.
호환성이 손상되는 변경 릴리스
데이터 API 작성기의 호환성이 손상되는 변경 버전은 이전 버전과 호환되지 않습니다. 기존 클라이언트 코드에서 호환성이 손상되는 변경 버전을 채택하려면 클라이언트가 이전 버전을 대상으로 할 때와 똑같이 동작하도록 코드를 변경해야 할 수 있습니다.
호환성이 손상되는 변경 버전은 호환성이 손상되는 변경 목록 문서 및 GitHub 릴리스의 변경 설명에서 발표됩니다. 변경 내용이 중요한 보안, 개인 정보 보호 또는 법적 문제를 수정하지 않는 한 미리 보기/릴리스 후보 버전을 게시하면 호환성이 손상되는 변경 버전보다 우선합니다. 이전 버전의 Data API Builder는 GitHub 릴리스 페이지에서 계속 사용할 수 있지만 버그 수정을 포함할 수 있는 최신 릴리스로 업그레이드하는 것이 좋습니다.
미리 보기 릴리스
데이터 API 작성기 미리 보기 릴리스는 버전 관리 체계로 X.Y.Z-rc 식별됩니다. -rc 접미사는 빌드가 "릴리스 후보"임을 나타냅니다. 미리 보기 릴리스는 새로운 기능 및 기타 변경 내용에 대한 피드백을 수집하는 데 사용됩니다.
마지막 안정적인 버전에서 의도적으로 중요한 변경을 수행하지 않는 한 안정적인 최신 릴리스 및 새로운 미리 보기 기능의 모든 것을 사용하여 다음 미리 보기 버전을 게시합니다. 다음 데이터 API 작성기 업데이트는 미리 보기 버전 간에 추가한 새로운 미리 보기 기능 중 일부를 중단할 수 있습니다. 이 호환성이 손상되는 동작은 다시 작동하도록 코드를 변경해야 할 수 있음을 의미합니다.
미리 보기 버전은 장기 또는 프로덕션용이 아닙니다. 안정적인 새 또는 미리 보기 버전을 사용할 수 있게 되면 이전 미리 보기 버전에 더 이상 액세스할 수 없을 수 있습니다. 새 기능을 적극적으로 작업하고 릴리스 직후 미리 보기가 아닌 버전으로 전환할 준비가 된 경우에만 미리 보기 버전을 사용하는 것이 가장 좋습니다. 미리 보기 버전의 일부 기능이 안정적인 새 버전에 포함된 경우 나머지 미리 보기 기능은 새로운 미리 보기 버전에 추가되어 사용해 볼 수 있습니다.
버전 변경 테이블
중요
변경 내용이 중요한 제품 버그, 법적, 보안 또는 개인 정보 보호 문제를 해결할 때 부 버전 또는 패치 릴리스에 호환성이 손상되는 변경이 도입될 수 있습니다.
| 릴리스 종류 | 이전 버전 | 새 버전 | 참고 |
|---|---|---|---|
| 변경 수준 | 1.Y.Z |
2.Y.Z |
새로운 기능 및 버그 수정과 호환성이 손상되는 변경 내용. |
| Stable | 1.1.Z |
1.2.Z |
변경 내용이 중요한 제품 버그, 법적, 보안 또는 개인 정보 보호 문제를 해결하지 않는 한 새로운 기능 및 버그 수정은 호환성이 손상되지 않습니다. |
| Stable | 1.1.1 |
1.1.2 |
변경 내용이 중요한 제품 버그, 법적, 보안 또는 개인 정보 보호 문제를 해결하지 않는 한 새로운 기능이나 호환성이 손상되는 변경 없이 버그 수정 |
| 미리 보기 | X.Y.1-rc |
X.Y.2-rc |
새로운 미리 보기 기능 및 버그 수정. 주 버전이 충돌하면 호환성이 손상되는 변경 내용이 포함됩니다. |
주요 변경 내용
보안의 우선 순위를 지정하고, 기능을 향상시키고, 코드 품질을 유지하기 위해 새로운 버전의 소프트웨어에는 호환성이 손상되는 변경이 포함될 수 있습니다. 우리는 신중한 아키텍처 선택을 통해 이러한 변화를 최소화하기 위해 노력하지만 여전히 발생할 수 있습니다. 이러한 경우 이를 알리고 가능한 솔루션을 제공하는 것이 최우선 과제입니다.
중요
변경 내용이 위반되지 않는 것으로 간주되거나 중요한 제품 버그 또는 법적, 보안 또는 개인 정보 보호 문제를 해결하기 위해 호환성이 손상되는 변경이 발생하는 경우 사전 통지 없이 변경할 수 있습니다.
호환성이 손상되는 변경이란?
호환성이 손상되는 변경은 중단을 방지하기 위해 애플리케이션을 업데이트해야 하는 수정입니다. 데이터 API 작성기에서 호환성이 손상되는 변경에는 REST API 계약 변경, GraphQL 스키마 생성 및 호환성 및 기능에 영향을 주는 기타 요소가 포함될 수 있습니다.
호환성이 손상되는 변경 예제
다음 예제는 데이터 API 작성기의 호환성이 손상되는 변경 내용에 대한 무중단 목록입니다.
- REST API 계약 수정
- GraphQL 스키마 생성의 변경
- 이전 버전과의 호환성에 영향을 주는 변경 내용
- API 또는 매개 변수 제거 또는 이름 바꾸기
- 오류 코드의 변경 내용
- 권한 정의 기능 조정
- 허용되는 매개 변수, 요청 필드 또는 응답 필드 제거
- 기본값이 없는 필수 매개 변수 또는 요청 필드 추가
- 의도한 API 엔드포인트 기능 수정
변경되지 않는 변경의 정의
호환성이 손상되지 않는 변경은 중단을 일으키지 않고 애플리케이션에 통합할 수 있는 변경을 의미합니다. 호환되지 않는 변경 내용은 일반적으로 구현 후에 전달됩니다. 애플리케이션은 사전 통지 없이 이러한 변경 내용을 처리하도록 설계되어야 합니다.
호환성이 손상되지 않는 변경 예제
다음 예제는 데이터 API 작성기의 무중단 변경 내용에 대한 무중단 목록입니다.
- 새 엔드포인트 소개
- 기존 엔드포인트에 메서드 추가
- 응답 및 요청에 새 필드 통합
- 응답 내 필드 순서 조정
- 선택적 요청 헤더 소개
- 데이터 길이 및 응답 크기 변경
- 오류 메시지 및 코드 변경
- HTTP 응답 코드 수정
- 생성된 OpenAPI 문서의 추가 메타데이터
호환성이 손상되는 변경 내용을 전달하려면 어떻게 해야 할까요?
주요 변경 내용에 대해 즉시 알려주는 것이 우선 순위입니다. GitHub의 데이터 API 작성기 릴리스 릴리스 정보 및 전용 호환성이 손상되는 변경 목록 문서에서 호환성이 손상되는 변경 알림을 찾을 수 있습니다.
현재 호환성이 손상되는 변경 목록
주요 변경 내용 및 기능 사용 중지는 이 문서에서 발표됩니다.
- 현재로서는 주요 변경 내용이 없습니다.