API Versioning

Source Compatibility

A public header file is installed to the include directory for any given CMake build configuration. Any other header file is a private header file.

A library's root namespace is declared in the global namespace scope, e.g. bsoncxx. All entities owned by the library are declared within the library's root namespace. Preprocessor macros owned by the library are prefixed with the library name instead, e.g. BSONCXX_EXAMPLE_MACRO.

The public API is the set of documented entities that are declared or defined in a public header file within the library's root namespace, with the following exceptions:

• The entity is explicitly documented as private or not intended for public use.

• The entity is declared in a detail namespace.

Including these exceptions, all other entities are considered to be part of the private API.

If there is an entity that should be documented, but is currently not, please submit a bug report.

Build System Compatibility

Although the public API depends on the configuration of the build system, the build system itself is NOT part of the public API.

Properties of the build system include:

• CMake configuration variables and corresponding behavior (with some exceptions: see below).

• The name, location, and contents of:

  • CMake source files (e.g. under ${PROJECT_SOURCE_DIR}).

  • CMake binary files (e.g. under ${PROJECT_BINARY_DIR}).

  • Installed library files (e.g. under {CMAKE_INSTALL_LIBDIR}).

  • Installed package files (e.g. under {CMAKE_INSTALL_LIBDIR}/pkgconfig).

However, build system configuration variables that directly impact the public API are considered part of the public API.

For example, C++17 polyfills declared in the bsoncxx::stdx namespace depend on configuration variables that determine the polyfill library used, e.g. CMAKE_CXX_STANDARD, BSONCXX_POLY_USE_STD, etc. A build configuration using CMAKE_CXX_STANDARD=17 produces a public API where bsoncxx::stdx::optional<T> == std::optional<T>. Because changing the type of bsoncxx::stdx::optional<T> such that it is no longer equivalent to std::optional<T> is a breaking change to the public API, changing the polyfill library selection behavior of CMAKE_CXX_STANDARD is also a breaking change to the public API. Therefore, CMAKE_CXX_STANDARD is considered part of the public API.

On the other hand, BSONCXX_OUTPUT_NAME controls the <basename> used to generate library and package filenames. Changing the name of a library or package file does not directly impact the public API (even if existing projects or applications may fail to configure, build, or link due to unexpected filenames). Therefore, BSONCXX_OUTPUT_NAME is not considered part of the public API.

Root Namespace Redeclarations

The API of C++ Driver libraries uses root namespace redeclarations of ABI namespace entities to facilitate incremental changes to the ABI. For more information, see ABI Root Namespace Redeclarations.

Entities that are not part of the stable ABI or the public API may be declared in the root namespace without being a member of any particular ABI namespace (e.g. bsoncxx::detail).

Deprecation and Removal

Before making a backward incompatible change, the existing entity or behavior will first be deprecated in a minor release. The backward incompatible change will be finalized in a major release that changes or removes the deprecated entity or behavior.

When able, the backward incompatible entity or behavior will be provided alongside its deprecated counterpart to provide an opportunity for a clean transition in the minor release. Users are strongly encouraged to apply the clean transition when such an opportunity is provided: please do not continue to use deprecated entities or behavior.

A deprecated entity or behavior will be documented using one or more of the following methods (not exhaustive):

• Use a *_DEPRECATED macro in the declaration of the entity.

• Include "deprecated" in the name of the entity.

• Explicitly document an entity or behavior as deprecated.