Versionado de API

Compatibilidad de origen

Un archivo de encabezado público se instala en el directorio de inclusión para cualquier configuración de compilación de CMake dada. Cualquier otro archivo de encabezado es un archivo de encabezado privado.

El espacio de nombres raíz de una biblioteca se declara en el ámbito del espacio de nombres global, por ejemplo bsoncxxTodas las entidades que pertenecen a la librería se declaran dentro del namespace raíz de la librería. Las macros de preprocesador propiedad de la librería poseen el nombre de prefijo de la librería, por ejemplo, BSONCXX_EXAMPLE_MACRO.

La API pública es el conjunto de entidades documentadas que se declaran o definen en un archivo de cabecera pública dentro del namespace raíz de la librería, con las siguientes excepciones:

• La entidad está documentada explícitamente como privada o no destinada al uso público.

• La entidad se declara en un namespace detail.

Incluidas estas excepciones, todas las demás entidades se consideran parte de la API privada.

Si hay una entidad que debe ser documentada, pero actualmente no lo está, envíe un informe de error.

Compatibilidad del sistema de compilación

Aunque la API pública depende de la configuración del sistema de compilación, el sistema de compilación en sí NO forma parte de la API pública.

Las propiedades del sistema de compilación incluyen:

• Variables de configuración de CMake y comportamiento correspondiente (con algunas excepciones: véase más abajo).

• El nombre, la ubicación y el contenido de:

  • Archivos fuente de CMake (por ejemplo, en ${PROJECT_SOURCE_DIR}).

  • Archivos binarios de CMake (por ejemplo, en ${PROJECT_BINARY_DIR}).

  • Archivos de la librería instalados (por ejemplo, en {CMAKE_INSTALL_LIBDIR}).

  • Archivos de paquetes instalados (por ejemplo, en {CMAKE_INSTALL_LIBDIR}/pkgconfig).

Sin embargo, las variables de configuración del sistema de construcción que impactan directamente en la API pública se consideran parte de la API pública.

Por ejemplo, los polyfills C++17 declarados en el espacio de nombres bsoncxx::stdx dependen de variables de configuración que determinan la librería de polyfills utilizada, por ejemplo, CMAKE_CXX_STANDARD, BSONCXX_POLY_USE_STD, etc. Una configuración de compilación usando CMAKE_CXX_STANDARD=17 produce una API pública donde bsoncxx::stdx::optional<T> == std::optional<T>. Dado que cambiar el tipo de bsoncxx::stdx::optional<T> de modo que ya no sea equivalente a std::optional<T> es un cambio disruptivo para la API pública, cambiar el comportamiento de selección de la librería de polyfills de CMAKE_CXX_STANDARD también es un cambio disruptivo para la API pública. Por lo tanto, se considera que CMAKE_CXX_STANDARD forma parte de la API pública.

Por otro lado, BSONCXX_OUTPUT_NAME controla el <basename> que se utiliza para generar los nombres de archivo de librerías y paquetes. Cambiar el nombre de una librería o archivo de paquete no afecta directamente a la API pública (aunque los Proyectos o aplicaciones existentes puedan fallar al configurar, compilar o vincular debido a nombres de archivos inesperados). Por lo tanto, BSONCXX_OUTPUT_NAME no se considera parte de la API pública.

Re-declaraciones del namespace raíz

La API de las bibliotecas de controladores de C++ utiliza redeclaraciones del espacio de nombres raíz de las entidades del espacio de nombres ABI para facilitar cambios incrementales en la ABI. Para más información, consulte Redeclaraciones del espacio de nombres raíz de la ABI.

Las entidades que no forman parte de la ABI estable o de la API pública pueden declararse en el espacio de nombres raíz sin ser miembro de ningún espacio de nombres ABI en particular (por ejemplo, bsoncxx::detail).

Obsolescencia y eliminación

Antes de realizar un cambio incompatible con la versión anterior, la entidad o el comportamiento existente primero se depreciará en una versión menor. El cambio que no es compatible hacia atrás se finalizará en una versión importante que cambie o remueva la entidad o el comportamiento obsoleto.

Cuando sea posible, la entidad o comportamiento incompatible con versiones anteriores se proporcionará junto con su contraparte obsoleta para permitir una transición limpia en la versión menor. Se recomienda encarecidamente a los usuarios que apliquen la transición limpia cuando se presente la oportunidad: por favor, no continúen utilizando entidades o comportamientos obsoletos.

Una entidad o comportamiento obsoleto se documentará mediante uno o varios de los siguientes métodos (no exhaustivos):

• Utilice un macro *_DEPRECATED en la declaración de la entidad.

• Incluye "obsoleto" en el nombre de la entidad.

• Documentar explícitamente una entidad o comportamiento como obsoleto.