API版本控制
C++ 驱动程序使用语义版本控制（又名 SemVer）进行 API 版本控制。
根据 SemVer 规范：
给定版本号 MAJOR.MINOR.PATCH，递增：
MAJOR 版本，当您进行不兼容的API更改时
以向后兼容的方式添加功能时的次要版本
进行向后兼容的错误修复时的补丁版本
出于 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 polyfill 取决于确定所使用的 polyfill 库的配置变量，例如 CMAKE_CXX_STANDARD 、 BSONCXX_POLY_USE_STD等 使用CMAKE_CXX_STANDARD=17的构建配置会生成一个公共 API，其中bsoncxx::stdx::optional<T> == std::optional<T> 。 由于更改bsoncxx::stdx::optional<T>的类型以使其不再等效于std::optional<T>是对公共 API 的一项重大更改，因此更改CMAKE_CXX_STANDARD的 polyfill 库选择行为也是对公共 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宏。在实体名称中包含“已弃用”。
将实体或行为明确记录为已弃用。