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 encabezado público dentro del espacio de nombres raíz de la biblioteca, 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 espacio de nombres 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: ver a continuación).

• 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 polyfills17 de C++ declarados en el espacio de nombres bsoncxx::stdx dependen de variables de configuración que determinan la biblioteca de polyfill utilizada, p. ej., CMAKE_CXX_STANDARD, BSONCXX_POLY_USE_STD, etc. Una configuración de compilación que utiliza CMAKE_CXX_STANDARD=17 genera una API pública donde bsoncxx::stdx::optional<T> == std::optional<T>. Dado que cambiar el tipo de bsoncxx::stdx::optional<T> de forma que ya no sea equivalente a std::optional<T> supone un cambio drástico en la API pública, modificar el comportamiento de selección de la biblioteca de polyfills de CMAKE_CXX_STANDARD también supone un cambio drástico en la API pública. Por lo tanto, CMAKE_CXX_STANDARD se considera 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).

Desuso y eliminación

Antes de realizar un cambio incompatible con versiones anteriores, la entidad o el comportamiento existente se descontinuará en una versión menor. El cambio incompatible con versiones anteriores se completará en una versión mayor que modifique o elimine la entidad o el comportamiento descontinuado.

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 una 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.