From 9da37abdf2cbc51e484ba4a781c46a1fb02616f8 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Wed, 25 Sep 2024 12:36:16 -0700 Subject: [PATCH 1/4] add upgrade page and link --- source/index.txt | 7 ++++ source/upgrade.txt | 98 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 105 insertions(+) create mode 100644 source/upgrade.txt diff --git a/source/index.txt b/source/index.txt index 0f61fd48..2e94fcd3 100644 --- a/source/index.txt +++ b/source/index.txt @@ -13,6 +13,7 @@ /aggregation /whats-new /compatibility + /upgrade libbson API Documentation <{+api-libbson+}> libmongoc API Documentation <{+api-libmongoc+}> @@ -102,6 +103,12 @@ Compatibility To learn about the versions of the {+mdb-server+} and the C language that are compatible with each version of the {+driver-short+}, see the :ref:`Compatibility ` section. +Upgrade Driver Versions +----------------------- + +Learn what changes you might need to make to your application to upgrade driver versions in the +:ref:`Upgrade Driver Versions ` section. + Learn ------ diff --git a/source/upgrade.txt b/source/upgrade.txt new file mode 100644 index 00000000..59412c27 --- /dev/null +++ b/source/upgrade.txt @@ -0,0 +1,98 @@ +.. _c-upgrade: + +================================= +Upgrade {+driver-short+} Versions +================================= + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: compatibility, backwards compatibility + +Overview +-------- + +This page describes the changes you must make to your application +when you upgrade to a new version of {+driver-short+}. + +Before you upgrade, perform the following actions: + +.. TODO: Link to platform support page +- Ensure the new {+driver-short+} version is compatible with the {+mdb-server+} versions + your application connects to and the platform your application runs on. For version + compatibility information, see the :ref:`{+driver-short+} Compatibility ` + page. +- Address any breaking changes between the current driver version + your application is using and your planned upgrade version in the + :ref:`Breaking changes ` section. To learn more about the + {+mdb-server+} release compatibility changes, see the + :ref:`Server Release Compatibility Changes ` section. + +.. TODO: Add a tip to use the stable API and link to corresponding page. + +.. _c-breaking-changes: + +Breaking Changes +---------------- + +.. note:: + + The {+driver-short+} follows :wikipedia:`semantic versioning. ` + The driver may break build systems or package compatibility in any release. Patch releases + may revert accidental API breaking changes. + +A breaking change is a change of a convention or a behavior starting in a specific +version of the driver. This type of change may prevent your application from working +properly if not addressed before upgrading the driver. + +The breaking changes in this section are categorized by the driver version that introduced +them. When upgrading driver versions, address all the breaking changes between the current +and upgrade versions. + +.. example:: Upgrading from Version 1.26 + + If you're upgrading the {+driver-short+} from version 1.26 to version 1.27, + address all breaking changes listed for versions 1.27.0 to 1.27.6, if any. + +.. _c-version-1.24.0-breaking-changes: + +Version 1.24.0 Breaking Changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The 1.24.0 release of libmongoc, one of the libraries constituting the C driver, introduces the following backwards +breaking changes: + +- Using Queryable Encryption requires MongoDB server version 7.0 and greater. + +.. _c-server-release-compatability-changes: + +Server Release Compatibility Changes +------------------------------------- + +A server release compatibility change is a modification +to the driver that discontinues support for a set of +{+mdb-server+} versions. + +The driver discontinues support for a {+mdb-server+} version after it reaches +end-of-life (EOL). + +To learn more about the MongoDB support for EOL products, +see the `Legacy Support Policy `__. + +.. _c-version-1.28.0-release-support-changes: + +Version 1.28.0 Release Support Changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- The v1.28.0 driver drops support for {+mdb-server+} v3.6 and earlier. To use any driver from v1.28.0 + and later, your {+mdb-server+} must be v4.0 or later. The v1.28.0 driver includes support for + {+mdb-server+} 8.0 features. To learn how to upgrade your {+mdb-server+} deployment, see + :manual:`Release Notes ` in the {+mdb-server+} manual. \ No newline at end of file From 80dc1d3def58c0abf57c847212ed7f2e3c3ed9a5 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Wed, 25 Sep 2024 12:53:13 -0700 Subject: [PATCH 2/4] update titles --- source/upgrade.txt | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/source/upgrade.txt b/source/upgrade.txt index 59412c27..c64cad02 100644 --- a/source/upgrade.txt +++ b/source/upgrade.txt @@ -1,8 +1,8 @@ .. _c-upgrade: -================================= -Upgrade {+driver-short+} Versions -================================= +======================= +Upgrade Driver Versions +======================= .. contents:: On this page :local: @@ -21,7 +21,7 @@ Overview -------- This page describes the changes you must make to your application -when you upgrade to a new version of {+driver-short+}. +when you upgrade to a new version of the {+driver-short+}. Before you upgrade, perform the following actions: @@ -32,7 +32,7 @@ Before you upgrade, perform the following actions: page. - Address any breaking changes between the current driver version your application is using and your planned upgrade version in the - :ref:`Breaking changes ` section. To learn more about the + :ref:`Breaking Changes ` section. To learn more about the {+mdb-server+} release compatibility changes, see the :ref:`Server Release Compatibility Changes ` section. @@ -67,10 +67,10 @@ and upgrade versions. Version 1.24.0 Breaking Changes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 1.24.0 release of libmongoc, one of the libraries constituting the C driver, introduces the following backwards +The 1.24.0 release of ``libmongoc``, one of the libraries constituting the C driver, introduces the following backwards breaking changes: -- Using Queryable Encryption requires MongoDB server version 7.0 and greater. +- Requires MongoDB server version 7.0 and greater to use Queryable Encryption. .. _c-server-release-compatability-changes: @@ -92,7 +92,7 @@ see the `Legacy Support Policy `_ Version 1.28.0 Release Support Changes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- The v1.28.0 driver drops support for {+mdb-server+} v3.6 and earlier. To use any driver from v1.28.0 - and later, your {+mdb-server+} must be v4.0 or later. The v1.28.0 driver includes support for - {+mdb-server+} 8.0 features. To learn how to upgrade your {+mdb-server+} deployment, see - :manual:`Release Notes ` in the {+mdb-server+} manual. \ No newline at end of file +- This driver version drops support for {+mdb-server+} versions 3.6 and earlier. To use any driver + from versions 1.28.0 and later, your {+mdb-server+} must be versions 4.0 or later. This driver version + includes support for {+mdb-server+} 8.0 features. To learn how to upgrade your {+mdb-server+} + deployment, see :manual:`Release Notes ` in the {+mdb-server+} manual. \ No newline at end of file From e78e2582bb704af538a4579de17fbacae05d227f Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Wed, 25 Sep 2024 13:04:27 -0700 Subject: [PATCH 3/4] edits --- source/upgrade.txt | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/source/upgrade.txt b/source/upgrade.txt index c64cad02..752b3b9c 100644 --- a/source/upgrade.txt +++ b/source/upgrade.txt @@ -31,8 +31,8 @@ Before you upgrade, perform the following actions: compatibility information, see the :ref:`{+driver-short+} Compatibility ` page. - Address any breaking changes between the current driver version - your application is using and your planned upgrade version in the - :ref:`Breaking Changes ` section. To learn more about the + your application uses and your planned upgrade version in the + :ref:`Breaking Changes ` section. To learn more about {+mdb-server+} release compatibility changes, see the :ref:`Server Release Compatibility Changes ` section. @@ -67,10 +67,10 @@ and upgrade versions. Version 1.24.0 Breaking Changes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The 1.24.0 release of ``libmongoc``, one of the libraries constituting the C driver, introduces the following backwards -breaking changes: +The 1.24.0 release of ``libmongoc``, one of the libraries constituting the C driver, introduces +the following backward-breaking change: -- Requires MongoDB server version 7.0 and greater to use Queryable Encryption. +- Requires MongoDB server version 7.0 and later to use Queryable Encryption. .. _c-server-release-compatability-changes: @@ -94,5 +94,5 @@ Version 1.28.0 Release Support Changes - This driver version drops support for {+mdb-server+} versions 3.6 and earlier. To use any driver from versions 1.28.0 and later, your {+mdb-server+} must be versions 4.0 or later. This driver version - includes support for {+mdb-server+} 8.0 features. To learn how to upgrade your {+mdb-server+} + supports {+mdb-server+} 8.0 features. To learn how to upgrade your {+mdb-server+} deployment, see :manual:`Release Notes ` in the {+mdb-server+} manual. \ No newline at end of file From 2b7f650a4b3dfeac0e5714e23992a7edb40b9975 Mon Sep 17 00:00:00 2001 From: Stephanie Aurelio Date: Thu, 26 Sep 2024 08:58:57 -0700 Subject: [PATCH 4/4] implement MW feedback --- source/upgrade.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/source/upgrade.txt b/source/upgrade.txt index 752b3b9c..d291a3e8 100644 --- a/source/upgrade.txt +++ b/source/upgrade.txt @@ -7,7 +7,7 @@ Upgrade Driver Versions .. contents:: On this page :local: :backlinks: none - :depth: 1 + :depth: 2 :class: singlecol .. facet:: @@ -70,7 +70,7 @@ Version 1.24.0 Breaking Changes The 1.24.0 release of ``libmongoc``, one of the libraries constituting the C driver, introduces the following backward-breaking change: -- Requires MongoDB server version 7.0 and later to use Queryable Encryption. +- Requires {+mdb-server+} version 7.0 and later to use Queryable Encryption. .. _c-server-release-compatability-changes: @@ -84,8 +84,8 @@ to the driver that discontinues support for a set of The driver discontinues support for a {+mdb-server+} version after it reaches end-of-life (EOL). -To learn more about the MongoDB support for EOL products, -see the `Legacy Support Policy `__. +To learn more about MongoDB support for EOL products, +see the `Legacy Support Policy. `__ .. _c-version-1.28.0-release-support-changes: @@ -93,6 +93,6 @@ Version 1.28.0 Release Support Changes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - This driver version drops support for {+mdb-server+} versions 3.6 and earlier. To use any driver - from versions 1.28.0 and later, your {+mdb-server+} must be versions 4.0 or later. This driver version + from versions 1.28.0 and later, your {+mdb-server+} must be version 4.0 or later. This driver version supports {+mdb-server+} 8.0 features. To learn how to upgrade your {+mdb-server+} deployment, see :manual:`Release Notes ` in the {+mdb-server+} manual. \ No newline at end of file