CXX-2967 Document the Stable ABI Compatibility Policy

[eramongodb]

Resolves CXX-2967. This is a documentation-only PR.

Running hugo server in the docs directory to live-preview the changes in a web browser is recommended.

This PR aims to expand and clarify our API and ABI compatibility policies. This will serve as a reference for all stable ABI changes going forward. This should be established before we set the ABI version number to its first integer value and commit to ABI stability. The API compatibility policy is updated accordingly.

Notable points include:

• Explicit definitions of what constitutes the "public API" and "stable ABI" for which we are committed to communicating compatibility for with the API and ABI version numbers respectively (see quotes from SemVer and Drepper).
  • Exclude most build system properties from the public API (e.g. library and package filenames) while making an effort to keep sensible ones included (e.g. CMAKE_CXX_STANDARD).
  • Include the soname as part of the stable ABI (e.g. library filename), except on Windows (where the soname convention doesn't apply).
  • Exclude entities and symbols explicitly documented as "private", "experimental", etc. so features can be added and developed without immediately committing to stability (or so they can be "soft-removed" via documentation without physically breaking compatibility).
• Describe the expected evolution of the API and ABI, including deprecation and removal, and when a given change requires updating the API and ABI version numbers.
• Document the existence and purpose of root namespace redeclarations w.r.t. ABI namespaces as well as the ABI namespace directory structure of public headers.
• Improve tips for using CMake package config and pkg-config files, strongly recommending use of CMake package config files, as well as discouraging manual configuration (although not outright declaring it unsupported).
• Improve MSVC-only documentation to cover package files and static libraries.

The stable ABI compatibility policy should be compatible with shared library versioning policies for mainstream package distributions. Both the ABI and API stability policy should be consistent with established practice for the CXX Driver, but refined to clearly set boundaries on what we consider in-scope and out-of-scope w.r.t. stability (such as build system properties).