Control de versiones de API

Compatibilidad de fuentes

Se instala un archivo de encabezado público en el directorio de inclusión para cualquier configuración de compilación de CMake. Cualquier otro archivo de encabezado es 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 propiedad de la biblioteca se declaran dentro del espacio de nombres raíz de la biblioteca. Las macros de preprocesador propiedad de la biblioteca llevan como prefijo el nombre de la biblioteca, p. ej., 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 debería estar 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, bajo ${PROJECT_BINARY_DIR}).

  • Archivos de biblioteca 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 compilació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> utilizado para generar los nombres de archivo de bibliotecas y paquetes. Cambiar el nombre de una biblioteca o paquete no afecta directamente a la API pública (incluso si los proyectos o aplicaciones existentes pueden fallar al configurarse, compilarse o enlazarse debido a nombres de archivo inesperados). Por lo tanto, BSONCXX_OUTPUT_NAME no se considera parte de la API pública.

Redeclaraciones del espacio de nombres 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 miembros 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á utilizando uno o más de los siguientes métodos (no exhaustivos):

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

• Incluya “obsoleto” en el nombre de la entidad.

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