API 버전 관리
C++ 드라이버는 API 버전 관리에 시맨틱 버전 관리(SemVer라고도 함)를 사용합니다.
버전 번호 MAJOR.MINOR.PATCH가 주어지면 다음을 증가시킵니다.
호환되지 않는 API 변경 시 주요 버전
이전 버전과 호환되는 방식으로 기능을 추가하는 경우의 마이너 버전
이전 버전과 호환되는 버그 수정 시 PATCH 버전
API 버전 관리를 위해 공개 API 와 비공개 API 를 구분합니다.
이 시스템이 작동하려면 먼저 공개 API를 선언해야 합니다. 이는 문서로 구성되거나 코드 자체에 의해 시행될 수 있습니다. 그럼에도 불구하고 이 API는 명확하고 정확해야 합니다. 공개 API를 식별한 후에는 버전 번호를 특정 단위로 변경하여 변경 사항을 알립니다.*
API 버전 번호는 SemVer 및 아래의 공개 API 정의에 따라 업데이트됩니다.
중요
공개 API의 안정성만이 API 버전 번호로 전달됩니다. 비공개 API에 대한 이전 버전과 호환되지 않는 변경 사항은 API 버전 번호로 전달되지 않습니다.
소스 호환성
공개 헤더 파일 은 지정된 CMake 빌드 구성에 대한 포함 디렉토리에 설치됩니다. 다른 모든 헤더 파일은 비공개 헤더 파일 입니다.
라이브러리의 루트 네임스페이스 는 전역 네임스페이스 범위에서 선언됩니다. bsoncxx. 라이브러리가 소유한 모든 엔터티는 라이브러리의 루트 네임스페이스 내에서 선언됩니다. 라이브러리가 소유한 전처리기 매크로에는 대신 라이브러리 이름이 접두사로 붙습니다. BSONCXX_EXAMPLE_MACRO.
공개 API 는 라이브러리의 루트 네임스페이스 내의 공개 헤더 파일에서 선언되거나 정의된 문서화된 엔터티의 집합이며, 다음과 같은 예외가 있습니다.
엔티티가 비공개 또는 공개용이 아닌 것으로 명시적으로 문서화되어 있습니다.
엔티티가
detail네임스페이스에서 선언되었습니다.
이러한 예외를 포함하여 다른 모든 엔터티는 비공개 API 의 일부로 간주됩니다.
문서화 해야 하지만 현재 문서화되지 않은 엔터티가 있는 경우 버그 보고서를 제출하세요.
중요
공개 엔터티의 문서화된 동작도 공개 API의 일부로 간주됩니다. 문서화되지 않은 동작은 라이브러리 수준에서 정의되지 않은 동작으로 간주되어 지원되지 않습니다. 문서화 해야 하지만 현재 문서화되지 않은 동작이 있는 경우 버그 보고서를 제출하세요.
참고
공개 API 의 일부인 일부 엔터티는 안정적인 ABI의 일부가 아닐 수 있습니다. 반대로 안정적인 ABI의 일부인 일부 기호는 공개 API 의 일부가 아닐 수 있습니다. ABI 버전 관리 정책을 참조하세요.
빌드 시스템 호환성
공개 API 는 빌드 시스템의 구성에 따라 달라지지만, 빌드 시스템 자체는 공개 API 의 일부가 아닙니다 .
빌드 시스템의 속성은 다음과 같습니다.
CMake 구성 변수 및 해당 동작(일부 예외 있음: 아래 참조).
다음의 이름, 위치 및 내용:
CMake 소스 파일(예:
${PROJECT_SOURCE_DIR}).CMake 바이너리 파일(예:
${PROJECT_BINARY_DIR}).설치된 라이브러리 파일(예:
{CMAKE_INSTALL_LIBDIR}).설치된 패키지 파일(예:
{CMAKE_INSTALL_LIBDIR}/pkgconfig).
그러나 공개 API에 직접 영향을 미치는 빌드 시스템 구성 변수는 공개 API의 일부로 간주됩니다.
예를 들어 bsoncxx::stdx 네임스페이스에 선언된 C++17 폴리필은 사용되는 폴리필 라이브러리를 결정하는 구성 변수에 따라 달라집니다. CMAKE_CXX_STANDARD, BSONCXX_POLY_USE_STD 등 CMAKE_CXX_STANDARD=17 를 사용하는 빌드 구성은 bsoncxx::stdx::optional<T> == std::optional<T> 인 공개 API를 생성합니다. bsoncxx::stdx::optional<T> 유형을 변경하여 더 이상 std::optional<T> 와 동일하지 않은 것은 공개 API의 호환성이 손상되는 변경이므로, CMAKE_CXX_STANDARD 의 폴리필 라이브러리 선택 동작을 변경하는 것도 공개 API의 호환성이 손상되는 변경입니다. 따라서 CMAKE_CXX_STANDARD 는 공개 API의 일부로 간주됩니다.
반면에 BSONCXX_OUTPUT_NAME 는 라이브러리 및 패키지 파일 이름을 생성하는 데 사용되는 <basename> 를 제어합니다. 라이브러리 또는 패키지 파일의 이름을 변경해도 공개 API에는 직접적인 영향을 미치지 않습니다(기존 프로젝트 또는 애플리케이션이 예기치 않은 파일 이름으로 인해 구성, 빌드 또는 연결에 실패할 수 있는 경우 포함). 따라서 BSONCXX_OUTPUT_NAME 는 공개 API의 일부로 간주 되지 않습니다 .
참고
빌드 구성별로 공개 API의 안정성을 지원합니다. 다양한 빌드 구성에서 공개 API의 호환성을 지원하지 않습니다. 예를 들어, CMAKE_BUILD_TYPE=Debug 을 사용하여 빌드 구성을 사용하여 생성한 공개 API는 CMAKE_BUILD_TYPE=Release 빌드 구성을 사용하여 생성된 공개 API에 대해 컴파일된 프로그램과 호환되지 않을 것으로 예상됩니다. (이는 Visual Studio와 같은 다중 구성 생성기를 사용할 때 특히 중요합니다!)
루트 네임스페이스 재선언
C++ 드라이버 라이브러리의 API는 ABI 네임스페이스 엔터티의 루트 네임스페이스 재선언을 사용하여 ABI에 대한 증분 변경을 용이하게 합니다. 자세한 내용은 ABI 루트 네임스페이스 재선언을 참조하세요.
안정적인 ABI 또는 공개 API의 일부가 아닌 엔터티는 특정 ABI 네임스페이스의 멤버가 아니어도 루트 네임스페이스에서 선언할 수 있습니다(예: bsoncxx::detail).
지원 중단 및 제거
이전 버전과 호환되지 않는 변경을 수행하기 전에 먼저 기존 엔터티 또는 동작이 마이너 출시하다 에서 더 이상 사용되지 않습니다. 이전 버전과 호환되지 않는 변경 사항은 더 이상 사용되지 않는 엔터티 또는 동작을 변경하거나 제거하는 주요 출시하다 로 확정됩니다.
가능한 경우 이전 버전과 호환되지 않는 엔터티 또는 동작은 더 이상 사용되지 않는 엔터티 또는 동작과 함께 제공되어 마이너 릴리스에서 깔끔하게 전환할 수 있는 기회를 제공합니다. 사용자는 이러한 기회가 있을 때 클린 전환을 적용할 것을 강력히 권장합니다. 더 이상 사용되지 않는 엔터티나 동작을 계속 사용하지 마세요.
참고
마이너 릴리스에서 깨끗한 전환 경로를 제공하는 것이 항상 가능한 것은 아닙니다.
더 이상 사용되지 않는 엔터티 또는 동작은 다음 방법 중 하나 이상을 사용하여 문서화됩니다(완전하지 않음).
엔터티 선언에
*_DEPRECATED매크로를 사용합니다.엔터티 이름에 'deprecated'를 포함합니다.
엔티티 또는 동작을 더 이상 사용되지 않는 것으로 명시적으로 문서화합니다.