Skip to content

Commit e53a9f3

Browse files
norareidynorareidy
authored
DOCSP-45586: Remove What's New breaking changes (#80)
* DOCSP-45586: Remove What's New breaking changes * remove admonitions * depth * EC feedback from other PR * EC feedback 2
1 parent 9fbe06c commit e53a9f3

File tree

2 files changed

+142
-154
lines changed

2 files changed

+142
-154
lines changed

‎source/upgrade.txt‎

Lines changed: 130 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ Upgrade Driver Versions
77
.. contents:: On this page
88
:local:
99
:backlinks: none
10-
:depth: 1
10+
:depth: 2
1111
:class: singlecol
1212

1313
.. facet::
@@ -40,10 +40,8 @@ Before you upgrade, perform the following actions:
4040
upgrading driver versions, use the
4141
:ref:`{+stable-api+} <cpp-stable-api>`.
4242

43-
.. _cpp-breaking-changes:
44-
45-
Breaking Changes
46-
----------------
43+
Definition of Breaking Changes
44+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4745

4846
.. note::
4947

@@ -61,17 +59,79 @@ The breaking changes in this section are categorized by the driver version that
6159
them. When upgrading driver versions, address all the breaking changes between the current
6260
and upgrade versions.
6361

64-
.. example:: Upgrading from Version 3.0
62+
.. example:: Upgrading to Version 4.0
63+
64+
If you're upgrading the {+driver-short+} from version 3.x to version 4.0,
65+
address all breaking changes that are listed for versions 3.x up to and
66+
including version 4.0
67+
68+
Types of Breaking Changes
69+
~~~~~~~~~~~~~~~~~~~~~~~~~
70+
71+
New versions of the {+driver-short+} can introduce the following types of breaking changes:
72+
73+
- **API** changes concern the API of the {+driver-short+} libraries. These changes are
74+
accompanied by an API major version bump. You might need to edit C++ source code
75+
in your project to address these changes.
76+
77+
.. example::
78+
79+
- Removes the declaration of function ``v1::func()``. (The definition is still
80+
provided for ABI compatibility.)
81+
- Removes the inline function ``v_noabi::func()``.
82+
- Removes ``v_noabi::func()``.
83+
- Changes the redeclaration of ``bsoncxx::foo`` from ``v1::foo`` to ``v2::foo``.
84+
To continue using the old interface, qualify ``bsoncxx::foo`` as ``bsoncxx::v1::foo``.
6585

66-
If you're upgrading the {+driver-short+} from version 3.0 to version 3.10,
67-
address all breaking changes listed for versions 3.1 to 3.10, if any.
86+
- **ABI** changes concern the ABI of the {+driver-short+} libraries. These changes are
87+
accompanied by an ABI version bump, and may also be accompanied by an API major version
88+
bump. You might need to rebuild your project or edit your C++ source code to address
89+
these changes.
6890

91+
ABI stability is **not** supported for symbols corresponding to entities declared in
92+
the ``v_noabi`` namespace. Breaking changes for such symbols are not necessarily
93+
accompanied by an ABI version bump.
94+
95+
.. example::
96+
97+
- Removes the exported symbol ``v_noabi::func()``.
98+
- Removes the exported symbol ``v1::func()``.
99+
- Removes the exported symbols for ``v1::type``.
100+
101+
- **Build system** changes concern the build system or packaging of the {+driver-short+}
102+
libraries. These changes are not necessarily accompanied by either an API major version
103+
bump or an ABI version bump.
104+
To address these changes, you might need to modify your build system configurations or
105+
update your project's package or dependency management settings. You might also need to
106+
modify or rebuild your C++ source code.
107+
108+
.. example::
109+
110+
- Removes the ``ENABLE_FOO`` configuration variable.
111+
- Changes the default value of the ``ENABLE_BAR`` configuration variable from
112+
``OFF`` to ``ON``.
113+
- Drops support for platform A, compiler B, or architecture C.
114+
115+
.. _cpp-breaking-changes:
116+
117+
Breaking Changes
118+
----------------
119+
120+
The following sections describe the breaking changes introduced by
121+
each driver version release.
122+
123+
.. _upcoming-breaking-changes:
69124
.. _version-4.0-breaking-changes:
70125

71-
Version 4.0 Breaking Changes
72-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
126+
Version 4.0
127+
~~~~~~~~~~~
128+
129+
.. _version-4.0-build-system-breaking:
73130

74-
This driver version introduces the following breaking changes:
131+
Build System Breaking Changes in v4.0
132+
`````````````````````````````````````
133+
134+
The v4.0 driver introduces the following breaking changes to the build system:
75135

76136
- Drops support for the Boost and MNMLSTC/core external polyfill libraries. You can no
77137
longer set the following configuration options:
@@ -81,61 +141,99 @@ This driver version introduces the following breaking changes:
81141
- ``BSONCXX_POLY_USE_SYSTEM_MNMLSTC``.
82142
- ``BSONCXX_POLY_USE_BOOST``.
83143

144+
API Breaking Changes in v4.0
145+
````````````````````````````
146+
147+
The v4.0 driver introduces the following breaking changes to the API:
148+
149+
- Drops support for configuring ``bsoncxx::stdx::string_view`` and
150+
``bsoncxx::stdx::optional<T>`` as aliases for Boost or MNMLSTC/core
151+
library equivalents. For context, see the :ref:`Build System Breaking Changes
152+
<version-4.0-build-system-breaking>` section.
153+
154+
ABI Breaking Changes in v4.0
155+
````````````````````````````
156+
157+
The v4.0 driver introduces the following breaking changes to the ABI:
158+
159+
- Drops support for configuring ``bsoncxx::stdx::string_view`` and
160+
``bsoncxx::stdx::optional<T>`` as aliases for Boost or MNMLSTC/core
161+
library equivalents. For context, see the :ref:`Build System Breaking Changes
162+
<version-4.0-build-system-breaking>` section.
163+
84164
.. _version-3.11-breaking-changes:
85165

86-
Version 3.11 Breaking Changes
87-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
166+
Version 3.11
167+
~~~~~~~~~~~~
88168

89-
This driver version introduces the following breaking changes:
169+
Build System Breaking Changes in v3.11
170+
``````````````````````````````````````
171+
172+
The v3.11 driver introduces the following breaking changes to the build system:
90173

91174
- Drops support for {+mdb-server+} v3.6.
92175
- Requires MongoDB C Driver v1.28.0 or later.
176+
177+
ABI Breaking Changes in v3.11
178+
`````````````````````````````
179+
180+
The v3.11 driver introduces the following breaking changes to the ABI:
181+
93182
- Removes export of the following private member functions in the bsoncxx
94183
ABI:
95-
96-
- ``bsoncxx::v_noabi::types::bson_value::value::value(const uint8_t*, uint32_t, uint32_t, uint32_t)``
184+
185+
- ``bsoncxx::v_noabi::types::bson_value::value::value(const uint8_t*,
186+
uint32_t, uint32_t, uint32_t)``
97187
- ``bsoncxx::v_noabi::types::bson_value::view::_init(void*)``
98-
- ``bsoncxx::v_noabi::types::bson_value::view::view(const uint8_t*, uint32_t, uint32_t, uint32_t)``
188+
- ``bsoncxx::v_noabi::types::bson_value::view::view(const uint8_t*,
189+
uint32_t, uint32_t, uint32_t)``
99190
- ``bsoncxx::v_noabi::types::bson_value::view::view(void*)``
100191

101192
- Removes export of the following private member functions in the mongocxx
102193
ABI:
103-
194+
104195
- ``mongocxx::v_noabi::options::change_stream::as_bson()``
105-
- ``mongocxx::v_noabi::options::aggregate::append(bsoncxx::v_noabi::builder::basic::document&)``
196+
- ``mongocxx::v_noabi::options::aggregate::append(
197+
bsoncxx::v_noabi::builder::basic::document&)``
106198
- ``mongocxx::v_noabi::options::index::storage_options()``
107-
199+
108200
- Declare all exported functions symbols with ``__cdecl`` when compiled with
109201
MSVC. This is an ABI breaking change if you use an alternative
110202
default calling convention when building projects.
111203

112204
.. _version-3.10-breaking-changes:
113205

114-
Version 3.10 Breaking Changes
115-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
206+
Version 3.10
207+
~~~~~~~~~~~~
116208

117-
This driver version introduces the following breaking changes:
209+
Build System Breaking Changes in v3.10
210+
``````````````````````````````````````
118211

119-
- Drops support for ``find_package(libbsoncxx)`` and ``find_package(libmongocxx)``.
120-
Use ``find_package(bsoncxx)`` and ``find_package(mongocxx)``
121-
instead.
212+
The v3.10 driver introduces the following breaking changes to the build system:
213+
214+
- Drops support for calling ``find_package(libbsoncxx)`` and
215+
``find_package(libmongocxx)``. Use ``find_package(bsoncxx)`` and
216+
``find_package(mongocxx)`` instead.
122217
- Drops support for the ``LIBBSONCXX_*`` and ``LIBMONGOCXX_*`` CMake variables
123218
provided by the legacy CMake package config files. Use the ``mongo::bsoncxx_*`` and
124219
``mongo::mongocxx_*`` CMake targets instead.
125-
- Removes the experimental C++ standard library (``BSONCXX_POLY_USE_STD_EXPERIMENTAL``) as a
126-
polyfill option.
220+
- Removes the ``BSONCXX_POLY_USE_STD_EXPERIMENTAL`` CMake option and drops support for selecting
221+
the experimental C++ standard library as a polyfill option.
127222

128223
.. _version-3.9-breaking-changes:
129224

130-
Version 3.9 Breaking Changes
131-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
225+
Version 3.9
226+
~~~~~~~~~~~
227+
228+
Build System Breaking Changes in v3.9
229+
`````````````````````````````````````
132230

133-
This driver version introduces the following breaking changes:
231+
The v3.9 driver introduces the following breaking changes:
134232

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

140238
Version 3.8 and Earlier
141239
~~~~~~~~~~~~~~~~~~~~~~~

‎source/whats-new.txt‎

Lines changed: 12 additions & 122 deletions
Original file line numberDiff line numberDiff line change
@@ -27,124 +27,25 @@ Learn what's new in:
2727
* :ref:`Version 3.10 <version-3.10>`
2828
* :ref:`Version 3.9 <version-3.9>`
2929

30-
Types of Breaking Changes
31-
~~~~~~~~~~~~~~~~~~~~~~~~~
32-
33-
New versions of the {+driver-short+} can introduce the following types of breaking changes:
34-
35-
- **API** changes concern the API of the {+driver-short+} libraries. These changes are
36-
accompanied by an API major version bump. You might need to edit C++ source code
37-
in your project to address these changes.
38-
39-
.. example::
40-
41-
- Removes the declaration of function ``v1::func()``. (The definition is still provided for ABI compatibility.)
42-
- Removes the inline function ``v_noabi::func()``.
43-
- Removes ``v_noabi::func()``.
44-
- Changes the redeclaration of ``bsoncxx::foo`` from ``v1::foo`` to ``v2::foo``.
45-
To continue using the old interface, qualify ``bsoncxx::foo`` as ``bsoncxx::v1::foo``.
46-
47-
- **ABI** changes concern the ABI of the {+driver-short+} libraries. These changes are
48-
accompanied by an ABI version bump, and may also be accompanied by an API major version
49-
bump. You might need to rebuild your project or edit your C++ source code to address
50-
these changes.
51-
52-
ABI stability is **not** supported for symbols corresponding to entities declared in
53-
the ``v_noabi`` namespace. Breaking changes for such symbols are not necessarily
54-
accompanied by an ABI version bump.
55-
56-
.. example::
57-
58-
- Removes the exported symbol ``v_noabi::func()``.
59-
- Removes the exported symbol ``v1::func()``.
60-
- Removes the exported symbols for ``v1::type``.
61-
62-
- **Build system** changes concern the build system or packaging of the {+driver-short+}
63-
libraries. These changes are not necessarily accompanied by either an API major version
64-
bump or an ABI version bump.
65-
To address these changes, you might need to modify your build system configurations or
66-
update your project's package or dependency management settings. You might also need to
67-
modify or rebuild your C++ source code.
68-
69-
.. example::
70-
71-
- Removes the ``ENABLE_FOO`` configuration variable.
72-
- Changes the default value of the ``ENABLE_BAR`` configuration variable from
73-
``OFF`` to ``ON``.
74-
- Drops support for platform A, compiler B, or architecture C.
75-
76-
.. _upcoming-breaking-changes:
7730
.. _version-4.0:
7831

7932
What's New in 4.0
8033
-----------------
8134

82-
.. _version-4.0-build-system-breaking:
83-
84-
.. warning:: Build System Breaking Changes
35+
.. warning:: Breaking Changes
8536

86-
The v4.0 driver introduces the following breaking changes to the build system:
87-
88-
- Drops support for the Boost and MNMLSTC/core external polyfill libraries. You can no
89-
longer set the following configuration options:
90-
91-
- ``ENABLE_BSONCXX_POLY_USE_IMPLS``. This option is implicitly set to ``ON``.
92-
- ``BSONCXX_POLY_USE_MNMLSTC``.
93-
- ``BSONCXX_POLY_USE_SYSTEM_MNMLSTC``.
94-
- ``BSONCXX_POLY_USE_BOOST``.
95-
96-
.. warning:: API Breaking Changes
97-
98-
The v4.0 driver introduces the following breaking changes to the API:
99-
100-
- Drops support for configuring ``bsoncxx::stdx::string_view`` and
101-
``bsoncxx::stdx::optional<T>`` as aliases for Boost or MNMLSTC/core
102-
library equivalents. For context, see the :ref:`Build System Breaking Changes
103-
<version-4.0-build-system-breaking>` admonition.
104-
105-
.. warning:: ABI Breaking Changes
106-
107-
The v4.0 driver introduces the following breaking changes to the ABI:
108-
109-
- Drops support for configuring ``bsoncxx::stdx::string_view`` and
110-
``bsoncxx::stdx::optional<T>`` as aliases for Boost or MNMLSTC/core
111-
library equivalents. For context, see the :ref:`Build System Breaking Changes
112-
<version-4.0-build-system-breaking>` admonition.
37+
{+driver-short+} v4.0 contains breaking changes. For more information, see
38+
:ref:`version-4.0-breaking-changes` in the Upgrade Driver Versions guide.
11339

11440
.. _version-3.11:
11541

11642
What's New in 3.11
11743
------------------
11844

119-
.. warning:: Build System Breaking Changes
120-
121-
The v3.11 driver introduces the following breaking changes to the build system:
122-
123-
- Drops support for {+mdb-server+} v3.6.
124-
- Requires MongoDB C Driver v1.28.0 or later.
45+
.. warning:: Breaking Changes
12546

126-
.. warning:: ABI Breaking Changes
127-
128-
The v3.11 driver introduces the following breaking changes to the ABI:
129-
130-
- Removes export of the following private member functions in the bsoncxx
131-
ABI:
132-
133-
- ``bsoncxx::v_noabi::types::bson_value::value::value(const uint8_t*, uint32_t, uint32_t, uint32_t)``
134-
- ``bsoncxx::v_noabi::types::bson_value::view::_init(void*)``
135-
- ``bsoncxx::v_noabi::types::bson_value::view::view(const uint8_t*, uint32_t, uint32_t, uint32_t)``
136-
- ``bsoncxx::v_noabi::types::bson_value::view::view(void*)``
137-
138-
- Removes export of the following private member functions in the mongocxx
139-
ABI:
140-
141-
- ``mongocxx::v_noabi::options::change_stream::as_bson()``
142-
- ``mongocxx::v_noabi::options::aggregate::append(bsoncxx::v_noabi::builder::basic::document&)``
143-
- ``mongocxx::v_noabi::options::index::storage_options()``
144-
145-
- Declare all exported functions symbols with ``__cdecl`` when compiled with
146-
MSVC. This is an ABI breaking change if you use an alternative
147-
default calling convention when building projects.
47+
{+driver-short+} v3.11 contains breaking changes. For more information, see
48+
:ref:`version-3.11-breaking-changes` in the Upgrade Driver Versions guide.
14849

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

@@ -164,17 +65,10 @@ on GitHub.
16465
What's New in 3.10
16566
------------------
16667

167-
.. warning:: Build System Breaking Changes
68+
.. warning:: Breaking Changes
16869

169-
The v3.10 driver introduces the following breaking changes to the build system:
170-
171-
- Drops support for calling ``find_package(libbsoncxx)`` and ``find_package(libmongocxx)``.
172-
Use ``find_package(bsoncxx)`` and ``find_package(mongocxx)``
173-
instead.
174-
- Drops support for the ``LIBBSONCXX_*`` and ``LIBMONGOCXX_*`` CMake variables
175-
provided by the legacy CMake package config files. Use the ``mongo::bsoncxx_*`` and
176-
``mongo::mongocxx_*`` CMake targets instead.
177-
- Removes the ``BSONCXX_POLY_USE_STD_EXPERIMENTAL`` CMake option and drops support for selecting the experimental C++ standard library as a polyfill option.
70+
{+driver-short+} v3.10 contains breaking changes. For more information, see
71+
:ref:`version-3.10-breaking-changes` in the Upgrade Driver Versions guide.
17872

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

@@ -223,14 +117,10 @@ on GitHub.
223117
What's New in 3.9
224118
-----------------
225119

226-
.. warning:: Build System Breaking Changes
227-
228-
The v3.9 driver introduces the following breaking changes:
120+
.. warning:: Breaking Changes
229121

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

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

0 commit comments

Comments
 (0)