DOCSP-45307: Drop external polyfill library support (#74)

* DOCSP-45307: Drop external polyfill library support

* JS feedback

* JS feedback 2

* tech review

* polyfills

* fixes

* EC feedback 2

* wording

* EC last feedback

Author: norareidy

source/api-abi-versioning.txt

@@ -193,8 +193,6 @@ Examples of expected library filenames (with a brief description of notable feat
 - ``bsoncxx-v_noabi-dhs-x64-v142-mdd.dll`` (debug build configuration)
 - ``bsoncxx-v_noabi-rts-x64-v142-md.dll`` (link with mongoc static libraries)
 - ``bsoncxx-v_noabi-rhi-x64-v142-md.dll`` (bsoncxx as polyfill library)
-- ``bsoncxx-v_noabi-rhm-x64-v142-md.dll`` (mnmlstc/core as polyfill library)
-- ``bsoncxx-v_noabi-rhb-x64-v142-md.dll`` (Boost as polyfill library)
 - ``bsoncxx-v1-rhs-x64-v142-md.dll``      (ABI version number 1)
 - ``bsoncxx-v2-rhs-x64-v142-md.dll``      (ABI version number 2)
 

source/get-started/download-and-install.txt

@@ -16,20 +16,22 @@ Download and Install
 
    .. step:: Install dependencies
 
-      Before you being developing, ensure you have the following dependencies
+      Before you being this tutorial, ensure you have the following dependencies
       installed in your development environment:
 
       - Compiler that supports C++17, such as `GCC <https://gcc.gnu.org/install/>`__, `Clang <https://clang.llvm.org/>`__,
         or `Visual Studio <https://visualstudio.microsoft.com/>`__
       - `CMake <https://cmake.org/>`__ v3.15 or later
       - `pkg-config <https://www.freedesktop.org/wiki/Software/pkg-config/>`__
 
-      .. note:: C++17 Polyfills
+      .. note:: Pre-C++17 Configurations
 
-         This tutorial configures the {+driver-short+} to use the C++17 standard
-         library. If you want to install the driver for pre-C++17 configurations,
-         you must choose a C++17 polyfill library. To learn more about C++17
-         polyfills, see the :ref:`cpp-polyfill-selection` guide.
+         Although C++11 is the minimum supported language version, this tutorial
+         configures the {+driver-short+} to use the C++17 standard library
+         as recommended by the :ref:`cpp-polyfill-config` section. If you want to install
+         the driver for pre-C++17 configurations, set the ``CMAKE_CXX_STANDARD``
+         configuration option to your C++ version. Then, the driver will automatically use
+         bsoncxx library polyfill implementations for required C++17 features.
 
    .. step:: Download the {+driver-short+}
 
@@ -56,6 +58,7 @@ Download and Install
 
                 cmake ..                                \
                     -DCMAKE_BUILD_TYPE=Release          \
+                    -DCMAKE_CXX_STANDARD=17                     \
                     -DMONGOCXX_OVERRIDE_DEFAULT_INSTALL_PREFIX=OFF
 
              This command instructs CMake to install ``mongocxx`` into the ``/usr/local`` directory.

source/index.txt

@@ -19,7 +19,6 @@ MongoDB C++ Driver
    Run a Command </run-command>
    Security </security>
    Specialized Data Formats </data-formats>
-   C++17 Polyfill </polyfill-selection>
    Advanced Configuration & Installation </advanced-installation>
    Thread & Fork Safety </thread-safety>
    API & ABI Versioning </api-abi-versioning>
@@ -83,12 +82,6 @@ Specialized Data Formats
 Learn how to work with specialized data formats and custom types in the
 :ref:`cpp-data-formats` section.
 
-Choose a C++17 Polyfill
------------------------
-
-Learn how to a choose a polyfill library implementation for
-pre-C++ 17 configurations in the :ref:`cpp-polyfill-selection` section.
-
 Advanced Installation Options
 -----------------------------
 
@@ -126,6 +119,29 @@ API Documentation
 For detailed information about types and methods in the {+driver-short+}, see
 the `{+driver-short+} API documentation <{+api+}>`__.
 
+.. _cpp-polyfill-config:
+
+C++17 Polyfill Configuration
+----------------------------
+
+.. important::
+
+   We recommend using the C++ standard library whenever possible by setting the
+   ``CMAKE_CXX_STANDARD`` configuration option to ``17`` or newer.
+
+The {+driver-long+} uses C++17 features ``std::optional<T>`` and ``std::string_view``.
+If you configure the driver with a pre-C++17 standard, the bsoncxx library provides
+polyfill implementations for these C++17 features. The driver uses the bsoncxx polyfill
+implementations when the ``CMAKE_CXX_STANDARD`` configuration option is set to a number
+less than ``17``. By default, this option is set to ``11``.
+
+.. warning:: 
+
+   The choice of polyfill library has a direct impact on the public API and ABI for the mongocxx
+   library. Changing the polyfill can lead to both source-breaking changes during compilation
+   and binary-breaking changes during linking or execution. To limit reliance on polyfill-specific
+   behavior, avoid using ``stdx::string_view`` and ``stdx::optional<T>`` with non-bsoncxx and non-mongocxx
+   library interfaces.
 
 Driver Status by Family and Version
 -----------------------------------

source/polyfill-selection.txt

@@ -66,11 +66,28 @@ and upgrade versions.
   If you're upgrading the {+driver-short+} from version 3.0 to version 3.10,
   address all breaking changes listed for versions 3.1 to 3.10, if any.
 
+.. _version-4.0-breaking-changes:
+
+Version 4.0 Breaking Changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This driver version introduces the following breaking changes:
+
+- Drops support for the Boost and MNMLSTC/core external polyfill libraries. You can no
+  longer set the following configuration options:
+
+  - ``ENABLE_BSONCXX_POLY_USE_IMPLS``. This option is implicitly set to ``ON``.
+  - ``BSONCXX_POLY_USE_MNMLSTC``.
+  - ``BSONCXX_POLY_USE_SYSTEM_MNMLSTC``.
+  - ``BSONCXX_POLY_USE_BOOST``.
+
 .. _version-3.11-breaking-changes:
 
 Version 3.11 Breaking Changes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+This driver version introduces the following breaking changes:
+
 - Drops support for {+mdb-server+} v3.6.
 - Requires MongoDB C Driver v1.28.0 or later.
 - Removes export of the following private member functions in the bsoncxx

source/upgrade.txt

@@ -22,6 +22,7 @@ Overview
 
 Learn what's new in:
 
+* :ref:`Version 4.0 <version-4.0>`
 * :ref:`Version 3.11 <version-3.11>`
 * :ref:`Version 3.10 <version-3.10>`
 * :ref:`Version 3.9 <version-3.9>`
@@ -73,18 +74,59 @@ New versions of the {+driver-short+} can introduce the following types of breaki
      - Drops support for platform A, compiler B, or architecture C.
 
 .. _upcoming-breaking-changes:
+.. _version-4.0:
+
+What's New in 4.0
+-----------------
+
+.. _version-4.0-build-system-breaking:
+
+.. warning:: Build System Breaking Changes
+
+   The v4.0 driver introduces the following breaking changes to the build system:
+   
+   - Drops support for the Boost and MNMLSTC/core external polyfill libraries. You can no
+     longer set the following configuration options:
+
+     - ``ENABLE_BSONCXX_POLY_USE_IMPLS``. This option is implicitly set to ``ON``.
+     - ``BSONCXX_POLY_USE_MNMLSTC``.
+     - ``BSONCXX_POLY_USE_SYSTEM_MNMLSTC``.
+     - ``BSONCXX_POLY_USE_BOOST``.
+
+.. warning:: API Breaking Changes
+
+   The v4.0 driver introduces the following breaking changes to the API:
+
+   - Drops support for configuring ``bsoncxx::stdx::string_view`` and
+     ``bsoncxx::stdx::optional<T>`` as aliases for Boost or MNMLSTC/core
+     library equivalents. For context, see the :ref:`Build System Breaking Changes
+     <version-4.0-build-system-breaking>` admonition.
+
+.. warning:: ABI Breaking Changes
+
+   The v4.0 driver introduces the following breaking changes to the ABI:
+
+   - Drops support for configuring ``bsoncxx::stdx::string_view`` and
+     ``bsoncxx::stdx::optional<T>`` as aliases for Boost or MNMLSTC/core
+     library equivalents. For context, see the :ref:`Build System Breaking Changes
+     <version-4.0-build-system-breaking>` admonition.
 
 .. _version-3.11:
 
 What's New in 3.11
 ------------------
 
-.. warning:: Breaking Changes
+.. warning:: Build System Breaking Changes
+
+   The v3.11 driver introduces the following breaking changes to the build system:
 
-   The v3.11 driver introduces the following breaking changes:
-   
    - Drops support for {+mdb-server+} v3.6.
    - Requires MongoDB C Driver v1.28.0 or later.
+
+.. warning:: ABI Breaking Changes
+
+   The v3.11 driver introduces the following breaking changes to the ABI:
+   
    - Removes export of the following private member functions in the bsoncxx
      ABI: