API のバージョン管理
C++ ドライバーは、API のバージョン管理にセマンティック バージョニング (別名 SemVer) を使用します。
バージョン番号がMAJOR.MINOR.PATCHの場合、次の値を増やします。
互換性のない API 変更を行う場合のメジャー バージョン
下位互換性のある方法で機能を追加する場合の最小バージョン
下位互換性のあるバグ修正を行う場合は、PATCH バージョン
API のバージョン管理では、パブリック APIとプライベート APIを区別します。
For this system to work, you first need to declare a public API. これはドキュメントで構成されている場合や、コード自体によって強制される場合もあります。 いずれに加えて、この API は明確で正確であることが重要です。 公開 API を識別すると、その変更をバージョン番号に具体的な増分で送信します。
API バージョン番号は、SemVer と以下の公開 API の定義に従って更新されます。
重要
パブリック API の安定性のみが API バージョン番号によって伝達されます。 プライベート API に対する下位互換性のない変更は、 API バージョン番号では伝達されません。
ソースの互換性
公開ヘッダー ファイルは、特定の CSpec ビルド構成の包含ディレクトリにインストールされます。 その他のヘッダー ファイルはプライベート ヘッダー ファイル です。
ライブラリのルート名前空間は、グローバル名前空間スコープで宣言されます。例: bsoncxx 。 ライブラリが所有するすべてのエンティティは、ライブラリのルート名前空間内で宣言されます。 ライブラリが所有するプリプロセッサ スクリプトのプレフィックスは、代わりにライブラリ名が付けられます。例: BSONCXX_EXAMPLE_MACRO 。
公開 APIは、ライブラリのルート名前空間内の公開ヘッダー ファイルで宣言または定義されるドキュメント化されたエンティティのセットです。ただし、次の例外があります。
エンティティがプライベートまたはパブリックでの使用を意図していないとして明示的にドキュメント化されている。
エンティティは
detail名前空間で宣言されています。
これらの例外を含め、他のすべてのエンティティはプライベート APIの一部と見なされます。
ドキュメント化されるべきエンティティがあるが、現在はドキュメント化されていない場合は、バグレポートを送信してください。
重要
パブリック エンティティの文書化された動作も、パブリック API の一部と見なされます。 ドキュメントに記載されていない動作は、ライブラリレベルの未定義の動作と見なされ、サポートされていません。 ドキュメント化されるべき動作があるものの、現在はドキュメント化されていない場合は、バグレポートを送信してください。
注意
パブリック API の一部である一部のエンティティは、安定版 ABI の一部ではない場合があります。 逆に、安定版 ABI の一部であるシンボルの一部は、公開 API の一部ではない場合もあります。 ABI バージョン管理ポリシーを参照してください。
ビルド システムの互換性
パブリック API はビルド システムの構成に依存しますが、ビルド システム自体はパブリック API の一部ではありません。
ビルド システムのプロパティは次のとおりです。
CSpec 構成変数と対応する動作（一部の例外を除く）は以下を参照してください。
次の名前、場所、内容:
CMax ソースファイル（例:
${PROJECT_SOURCE_DIR}の下）。CMax バイナリ ファイル（例:
${PROJECT_BINARY_DIR}の下）。インストールされたライブラリ ファイル（例:
{CMAKE_INSTALL_LIBDIR}の下）。インストールされたパッケージ ファイル（例:
{CMAKE_INSTALL_LIBDIR}/pkgconfigの下）。
ただし、パブリック API に直接影響するビルド システム構成変数は、パブリック API の一部と見なされます。
たとえば、 bsoncxx::stdx名前空間で宣言された C++ 17ポリゴンは、使用されるポリゴン ライブラリを決定する構成変数に依存します。たとえば、 CMAKE_CXX_STANDARD 、 BSONCXX_POLY_USE_STDなど。 CMAKE_CXX_STANDARD=17を使用するビルド構成では、 bsoncxx::stdx::optional<T> == std::optional<T>のパブリック API が生成されます。 std::optional<T>と等しくないようにbsoncxx::stdx::optional<T>のタイプを変更することはパブリック API の重大な変更であるため、 CMAKE_CXX_STANDARDの多形ライブラリ選択動作を変更することもパブリック API の重大な変更になります。 したがって、 CMAKE_CXX_STANDARDは公開 API の一部と見なされます。
一方、 BSONCXX_OUTPUT_NAMEは、ライブラリとパッケージ ファイル名の生成に使用される<basename>を制御します。 ライブラリまたはパッケージ ファイルの名前を変更しても、パブリック API には直接影響しません（予期しないファイル名により既存のプロジェクトやアプリケーションが構成、ビルド、またはリンクに失敗した場合でも）。 したがって、 BSONCXX_OUTPUT_NAMEは公開 API の一部とは見なされません。
注意
ビルド構成 ごとのパブリック API の安定性をサポートします。 異なるビルド構成間でのパブリック API の互換性はサポートしていません。 たとえば、 CMAKE_BUILD_TYPE=Debugのビルド構成を使用して生成された公開 API は、 CMAKE_BUILD_TYPE=Releaseのビルド構成を使用して作成された公開 API に対してコンパイルされたプログラムと互換性がありません。 （Visual Studio などの複数構成のジェネレーターを使用する場合、特に重要です）
ルート名前空間の再宣言
C++ ドライバー ライブラリの API は、ABI 名前空間エンティティのルート名前空間再宣言を使用して、ABI への段階的な変更を容易にします。 詳細については、「 ABI ルート名前空間の再宣言 」を参照してください。
安定版 ABI またはパブリック API の一部ではないエンティティは、特定の ABI 名前空間のノードでなく、ルート名前空間で宣言できます（例: bsoncxx::detail ）。
非推奨と削除
下位互換性のない変更を行う前に、まず既存のエンティティまたは動作をマイナー リリースで廃止します。 下位互換性のない変更は、非推奨のエンティティまたは動作を変更または削除するメジャー リリースで最終化されます。
可能であれば、下位互換性のないエンティティまたは動作が非推奨のカウンターポートと合わせて提供され、マイナーなリリースでクリーンな移行を行う機会が提供されます。 このような機会が提供された場合は、クリーン移行を適用することを強くお勧めします。非推奨のエンティティや動作を引き続き使用しないでください。
注意
マイナー リリースでクリーンな移行パスを提供できない場合があります。
非推奨のエンティティまたは動作は、次の 1 つ以上のメソッドを使用して文書化されます（すべて網羅するものではありません）。
エンティティの宣言で
*_DEPRECATEDマイクロを使用します。エンティティの名前に "非推奨" を含めます。
エンティティまたは動作を非推奨として明示的にドキュメント化します。