Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DOCSP-45586: Remove What's New breaking changes #80

Merged
merged 5 commits into from
Nov 21, 2024
Merged

DOCSP-45586: Remove What's New breaking changes #80

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
34ea9ea
DOCSP-45586: Remove What's New breaking changes
norareidy Nov 21, 2024
edb7081
remove admonitions
norareidy Nov 21, 2024
ba38701
depth
norareidy Nov 21, 2024
7de60ec
EC feedback from other PR
norareidy Nov 21, 2024
e849e64
EC feedback 2
norareidy Nov 21, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
115 changes: 101 additions & 14 deletions source/upgrade.txt
View file
Open in desktop
eramongodb marked this conversation as resolved.
Show resolved Hide resolved
Original file line number Diff line number Diff line change
Expand Up @@ -66,12 +66,64 @@ 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.

Types of Breaking Changes
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Question/Suggestion: should we change the .. contents:: component to be depth level 2? Each of the main headers have a few subsections so might be helpful to include those in the page ToC. If changing this results in the ToC becoming too lengthy/unwieldy, feel free to leave

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I changed depth to 2 originally, but it did make the TOC look overly complicated (since the subheaders have long titles). So I think I'll leave as is

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nvm changed back to 2 after restructuring!

Copy link
Collaborator

@eramongodb eramongodb Nov 21, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Possibly related (I do not fully understand the depth level discussion), I am in favor of removing the "Breaking Change Definition" and "Types of Breaking Changes" headers entirely while preserving the remaining content as-is, such that the current contents of each section just become contents of "Overview".

On this page

  • Overview
  • Breaking Changes
    • Version 4.0
    • ...

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hm, Overview gets pretty long and disorganized if I remove those subheaders.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If so, I am fine with leaving them as-is.

~~~~~~~~~~~~~~~~~~~~~~~~~

New versions of the {+driver-short+} can introduce the following types of breaking changes:

- **API** changes concern the API of the {+driver-short+} libraries. These changes are
accompanied by an API major version bump. You might need to edit C++ source code
in your project to address these changes.

.. example::

- Removes the declaration of function ``v1::func()``. (The definition is still provided for ABI compatibility.)
- Removes the inline function ``v_noabi::func()``.
- Removes ``v_noabi::func()``.
- Changes the redeclaration of ``bsoncxx::foo`` from ``v1::foo`` to ``v2::foo``.
To continue using the old interface, qualify ``bsoncxx::foo`` as ``bsoncxx::v1::foo``.

- **ABI** changes concern the ABI of the {+driver-short+} libraries. These changes are
accompanied by an ABI version bump, and may also be accompanied by an API major version
bump. You might need to rebuild your project or edit your C++ source code to address
these changes.

ABI stability is **not** supported for symbols corresponding to entities declared in
the ``v_noabi`` namespace. Breaking changes for such symbols are not necessarily
accompanied by an ABI version bump.

.. example::

- Removes the exported symbol ``v_noabi::func()``.
- Removes the exported symbol ``v1::func()``.
- Removes the exported symbols for ``v1::type``.

- **Build system** changes concern the build system or packaging of the {+driver-short+}
libraries. These changes are not necessarily accompanied by either an API major version
bump or an ABI version bump.
To address these changes, you might need to modify your build system configurations or
update your project's package or dependency management settings. You might also need to
modify or rebuild your C++ source code.

.. example::

- Removes the ``ENABLE_FOO`` configuration variable.
- Changes the default value of the ``ENABLE_BAR`` configuration variable from
``OFF`` to ``ON``.
- Drops support for platform A, compiler B, or architecture C.

.. _upcoming-breaking-changes:
.. _version-4.0-breaking-changes:

Version 4.0 Breaking Changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
----------------------------

This driver version introduces the following breaking changes:
.. _version-4.0-build-system-breaking:

Build System Breaking Changes
eramongodb marked this conversation as resolved.
Show resolved Hide resolved
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The v4.0 driver introduces the following breaking changes to the build system:
eramongodb marked this conversation as resolved.
Show resolved Hide resolved

- Drops support for the Boost and MNMLSTC/core external polyfill libraries. You can no
longer set the following configuration options:
Expand All @@ -81,64 +133,99 @@ This driver version introduces the following breaking changes:
- ``BSONCXX_POLY_USE_SYSTEM_MNMLSTC``.
- ``BSONCXX_POLY_USE_BOOST``.

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>` section.

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>` section.

.. _version-3.11-breaking-changes:

Version 3.11 Breaking Changes
-----------------------------

Build System Breaking Changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This driver version introduces the following breaking changes:
The v3.11 driver introduces the following breaking changes to the build system:

- Drops support for {+mdb-server+} v3.6.
- Requires MongoDB C Driver v1.28.0 or later.

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:

- ``bsoncxx::v_noabi::types::bson_value::value::value(const uint8_t*, uint32_t, uint32_t, uint32_t)``
- ``bsoncxx::v_noabi::types::bson_value::view::_init(void*)``
- ``bsoncxx::v_noabi::types::bson_value::view::view(const uint8_t*, uint32_t, uint32_t, uint32_t)``
- ``bsoncxx::v_noabi::types::bson_value::view::view(void*)``

- Removes export of the following private member functions in the mongocxx
ABI:

- ``mongocxx::v_noabi::options::change_stream::as_bson()``
- ``mongocxx::v_noabi::options::aggregate::append(bsoncxx::v_noabi::builder::basic::document&)``
- ``mongocxx::v_noabi::options::index::storage_options()``

- Declare all exported functions symbols with ``__cdecl`` when compiled with
MSVC. This is an ABI breaking change if you use an alternative
default calling convention when building projects.

.. _version-3.10-breaking-changes:

Version 3.10 Breaking Changes
-----------------------------

Build System Breaking Changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This driver version introduces the following breaking changes:
The v3.10 driver introduces the following breaking changes to the build system:

- Drops support for ``find_package(libbsoncxx)`` and ``find_package(libmongocxx)``.
- Drops support for calling ``find_package(libbsoncxx)`` and ``find_package(libmongocxx)``.
Use ``find_package(bsoncxx)`` and ``find_package(mongocxx)``
instead.
- Drops support for the ``LIBBSONCXX_*`` and ``LIBMONGOCXX_*`` CMake variables
provided by the legacy CMake package config files. Use the ``mongo::bsoncxx_*`` and
``mongo::mongocxx_*`` CMake targets instead.
- Removes the experimental C++ standard library (``BSONCXX_POLY_USE_STD_EXPERIMENTAL``) as a
polyfill option.
- Removes the ``BSONCXX_POLY_USE_STD_EXPERIMENTAL`` CMake option and drops support for selecting
the experimental C++ standard library as a polyfill option.

.. _version-3.9-breaking-changes:

Version 3.9 Breaking Changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
----------------------------

Build System Breaking Changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This driver version introduces the following breaking changes:
The v3.9 driver introduces the following breaking changes:

- Removes support for exported targets from the CMake project build tree
- Drops support for macOS 10.14, macOS 10.15, and Ubuntu 14.04
- Requires MongoDB C Driver v1.25.0 or later
- Requires CMake v3.15 or later
- Requires CMake v3.15 or later to support the ``FetchContent`` module

Version 3.8 and Earlier
~~~~~~~~~~~~~~~~~~~~~~~
-----------------------

For driver versions 3.8 and earlier, see the
release notes and associated JIRA tickets for each release
Expand Down
134 changes: 12 additions & 122 deletions source/whats-new.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,124 +27,25 @@ Learn what's new in:
* :ref:`Version 3.10 <version-3.10>`
* :ref:`Version 3.9 <version-3.9>`

Types of Breaking Changes
~~~~~~~~~~~~~~~~~~~~~~~~~

New versions of the {+driver-short+} can introduce the following types of breaking changes:

- **API** changes concern the API of the {+driver-short+} libraries. These changes are
accompanied by an API major version bump. You might need to edit C++ source code
in your project to address these changes.

.. example::

- Removes the declaration of function ``v1::func()``. (The definition is still provided for ABI compatibility.)
- Removes the inline function ``v_noabi::func()``.
- Removes ``v_noabi::func()``.
- Changes the redeclaration of ``bsoncxx::foo`` from ``v1::foo`` to ``v2::foo``.
To continue using the old interface, qualify ``bsoncxx::foo`` as ``bsoncxx::v1::foo``.

- **ABI** changes concern the ABI of the {+driver-short+} libraries. These changes are
accompanied by an ABI version bump, and may also be accompanied by an API major version
bump. You might need to rebuild your project or edit your C++ source code to address
these changes.

ABI stability is **not** supported for symbols corresponding to entities declared in
the ``v_noabi`` namespace. Breaking changes for such symbols are not necessarily
accompanied by an ABI version bump.

.. example::

- Removes the exported symbol ``v_noabi::func()``.
- Removes the exported symbol ``v1::func()``.
- Removes the exported symbols for ``v1::type``.

- **Build system** changes concern the build system or packaging of the {+driver-short+}
libraries. These changes are not necessarily accompanied by either an API major version
bump or an ABI version bump.
To address these changes, you might need to modify your build system configurations or
update your project's package or dependency management settings. You might also need to
modify or rebuild your C++ source code.

.. example::

- Removes the ``ENABLE_FOO`` configuration variable.
- Changes the default value of the ``ENABLE_BAR`` configuration variable from
``OFF`` to ``ON``.
- 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
.. warning:: 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.
{+driver-short+} v4.0 contains breaking changes. For more information, see
:ref:`version-4.0-breaking-changes` in the Upgrade Driver Versions guide.

.. _version-3.11:

What's New in 3.11
------------------

.. warning:: Build System Breaking Changes

The v3.11 driver introduces the following breaking changes to the build system:

- Drops support for {+mdb-server+} v3.6.
- Requires MongoDB C Driver v1.28.0 or later.
.. warning:: Breaking Changes

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

- ``bsoncxx::v_noabi::types::bson_value::value::value(const uint8_t*, uint32_t, uint32_t, uint32_t)``
- ``bsoncxx::v_noabi::types::bson_value::view::_init(void*)``
- ``bsoncxx::v_noabi::types::bson_value::view::view(const uint8_t*, uint32_t, uint32_t, uint32_t)``
- ``bsoncxx::v_noabi::types::bson_value::view::view(void*)``

- Removes export of the following private member functions in the mongocxx
ABI:

- ``mongocxx::v_noabi::options::change_stream::as_bson()``
- ``mongocxx::v_noabi::options::aggregate::append(bsoncxx::v_noabi::builder::basic::document&)``
- ``mongocxx::v_noabi::options::index::storage_options()``

- Declare all exported functions symbols with ``__cdecl`` when compiled with
MSVC. This is an ABI breaking change if you use an alternative
default calling convention when building projects.
{+driver-short+} v3.11 contains breaking changes. For more information, see
:ref:`version-3.11-breaking-changes` in the Upgrade Driver Versions guide.

The v3.11 driver release includes the following new features:

Expand All @@ -164,17 +65,10 @@ on GitHub.
What's New in 3.10
------------------

.. warning:: Build System Breaking Changes
.. warning:: Breaking Changes

The v3.10 driver introduces the following breaking changes to the build system:

- Drops support for calling ``find_package(libbsoncxx)`` and ``find_package(libmongocxx)``.
Use ``find_package(bsoncxx)`` and ``find_package(mongocxx)``
instead.
- Drops support for the ``LIBBSONCXX_*`` and ``LIBMONGOCXX_*`` CMake variables
provided by the legacy CMake package config files. Use the ``mongo::bsoncxx_*`` and
``mongo::mongocxx_*`` CMake targets instead.
- Removes the ``BSONCXX_POLY_USE_STD_EXPERIMENTAL`` CMake option and drops support for selecting the experimental C++ standard library as a polyfill option.
{+driver-short+} v3.10 contains breaking changes. For more information, see
:ref:`version-3.10-breaking-changes` in the Upgrade Driver Versions guide.

The v3.10.0 driver release includes the following new features:

Expand Down Expand Up @@ -223,14 +117,10 @@ on GitHub.
What's New in 3.9
-----------------

.. warning:: Build System Breaking Changes

The v3.9 driver introduces the following breaking changes:
.. warning:: Breaking Changes

- Removes support for exported targets from the CMake project build tree
- Drops support for macOS 10.14, macOS 10.15, and Ubuntu 14.04
- Requires MongoDB C Driver v1.25.0 or later
- Requires CMake v3.15 or later to support the ``FetchContent`` module
{+driver-short+} v3.9 contains breaking changes. For more information, see
:ref:`version-3.9-breaking-changes` in the Upgrade Driver Versions guide.

The v3.9 driver release includes the following new features:

Expand Down
Loading