Controle de Versão da API
Nesta página
O driver C++ usa o controle de versão semântica (também conhecido como SemVer) para o controle de versão da API.
De acordo com a especificação do SemVer:
Dado um número de versão MAJOR.MINOR.PATCH, aumente o:
Versão MAJOR quando você faz alterações de API incompatíveis
Versão MINOR quando você adiciona funcionalidade de forma compatível com versões anteriores
Versão PATCH quando você faz correções de bug compatíveis com versões anteriores
Para fins de controle de versão da API, distinguimos entre a API pública e a API privada:
Para que esse sistema funcione, primeiro você precisa declarar uma API pública. Isso pode consistir em documentação ou ser imposto pelo próprio código. Independentemente disso, é importante que essa API seja clara e precisa. Depois de identificar sua API pública, você comunica as alterações com incrementos específicos no número da versão.*
O número da versão da API é atualizado de acordo com o SemVer e a definição da API pública abaixo.
Importante
Somente a estabilidade da API pública é comunicada pelo número da versão da API. As alterações anteriores (in)compatíveis à API privada não são comunicadas pelo número da versão da API.
Compatibilidade de fonte
Um arquivo de cabeçalho público é instalado no diretório de inclusão para qualquer configuração de compilação do CMake fornecida. Qualquer outro arquivo de cabeçalho é um arquivo de cabeçalho privado.
O namespace raiz de uma biblioteca é declarado no escopo do namespace global, por exemplo bsoncxx. Todas as entidades de propriedade da biblioteca são declaradas dentro do namespace raiz da biblioteca. As macros de pré-processador de propriedade da biblioteca são prefixadas com o nome da biblioteca, por exemplo BSONCXX_EXAMPLE_MACRO.
A API pública é o conjunto de entidades documentadas que são declaradas ou definidas em um arquivo de cabeçalho público dentro do namespace raiz da biblioteca, com as seguintes exceções:
A entidade é explicitamente documentada como privada ou não destinada ao uso público.
A entidade é declarada em um namespace
detail.
Incluindo essas exceções, todas as outras entidades são consideradas parte da API privada.
Se houver uma entidade que deve ser documentada, mas atualmente não é, envie um relatório de bug.
Importante
O comportamento documentado de uma entidade pública também é considerado parte da API pública. O comportamento que não é documentado é considerado comportamento indefinido no nível da biblioteca e não é suportado. Se houver um comportamento que deve ser documentado, mas atualmente não está, envie um relatório de bug.
Observação
Algumas entidades que fazem parte da API pública podem não fazer parte da ABI estável. Por outro lado, alguns símbolos que fazem parte da ABI estável podem não fazer parte da API pública. Consultea Política de Versão do ABI .
Construa a compatibilidade do sistema
Embora a API pública dependa da configuração do sistema de construção, o sistema de construção em si NÃO faz parte da API pública.
As propriedades do sistema de construção incluem:
Variáveis de configuração do CMake e comportamento correspondente (com algumas exceções: veja abaixo).
O nome, localização e conteúdo de:
Arquivos de origem do CMake (por exemplo abaixo de
${PROJECT_SOURCE_DIR}).Arquivos binários CMake (por exemplo abaixo de
${PROJECT_BINARY_DIR}).Arquivos de biblioteca instalados (por exemplo abaixo de
{CMAKE_INSTALL_LIBDIR}).Arquivos de pacotes instalados (por exemplo abaixo de
{CMAKE_INSTALL_LIBDIR}/pkgconfig).
No entanto, as variáveis de configuração do sistema de construção que afetam diretamente a API pública são consideradas parte da API pública.
Por exemplo, os polyfills C++17 declarados no namespace bsoncxx::stdx dependem de variáveis de configuração que determinam a biblioteca de polyfill usada, por exemplo CMAKE_CXX_STANDARD, BSONCXX_POLY_USE_STD, etc. Uma configuração de compilação usando CMAKE_CXX_STANDARD=17 produz uma API pública onde bsoncxx::stdx::optional<T> == std::optional<T>. Como alterar o tipo de bsoncxx::stdx::optional<T> modo que ele não seja mais equivalente a std::optional<T> é uma alteração significativa na API pública, alterar o comportamento de seleção da biblioteca de polyfill de CMAKE_CXX_STANDARD também é uma alteração significativa na API pública. Portanto, CMAKE_CXX_STANDARD é considerado parte da API pública.
Por outro lado, o BSONCXX_OUTPUT_NAME controla o <basename> utilizado para gerar nomes de arquivo de biblioteca e pacote. Alterar o nome de uma biblioteca ou arquivo de pacote não afeta diretamente a API pública (mesmo que os projetos ou aplicativos existentes possam falhar ao configurar, construir ou vincular devido a nomes de arquivo inesperados). Portanto, BSONCXX_OUTPUT_NAME não é considerado parte da API pública.
Observação
Apoiamos a estabilidade da API pública por configuração de compilação. Não aceitamos compatibilidade da API pública em diferentes configurações de compilação. Por exemplo, não se espera que uma API pública produzida utilizando uma configuração de compilação com CMAKE_BUILD_TYPE=Debug seja compatível com um programa compilado com uma API pública produzida utilizando uma configuração de compilação com CMAKE_BUILD_TYPE=Release. (Isto é particularmente importante ao utilizar geradores de múltiplas configurações, como o Visual Studio):
Redeclarações do namespace raiz
A API das bibliotecas de drivers C++ usa redeclarações de namespace raiz de entidades de namespace ABI para facilitar alterações incrementais na ABI. Para obter mais informações, consulte Redeclarações de namespace raiz da ABI.
As entidades que não fazem parte da ABI estável ou da API pública podem ser declaradas no namespace raiz sem ser membros de nenhum namespace da ABI específico (por exemplo bsoncxx::detail).
Descontinuação e remoção
Antes de fazer uma alteração incompatível com versões anteriores, a entidade ou comportamento existente será preterido em uma versão menor. A alteração incompatível com versões anteriores será finalizada em uma versão principal que altere ou remova a entidade ou comportamento obsoleto.
Quando possível, a entidade ou comportamento incompatível com versões anteriores será fornecido junto com sua contraparte obsoleta para fornecer uma oportunidade para uma transição limpa na versão menor. Os usuários são altamente encorajados a aplicar a transição limpa quando essa oportunidade for fornecida: não continue a usar entidades ou comportamentos obsoletos.
Observação
Fornecer um caminho de transição limpo em uma versão menor nem sempre é possível.
Uma entidade ou comportamento obsoleto será documentado usando um ou mais dos seguintes métodos (não exaustivos):
Utilize uma macro
*_DEPRECATEDna declaração da entidade.Incluir "obsoleto" no nome da entidade.
Documente explicitamente uma entidade ou comportamento como obsoleto.