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..d291a3e8 --- /dev/null +++ b/source/upgrade.txt @@ -0,0 +1,98 @@ +.. _c-upgrade: + +======================= +Upgrade Driver Versions +======================= + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :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 the {+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 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. + +.. 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 backward-breaking change: + +- Requires {+mdb-server+} version 7.0 and later to use Queryable Encryption. + +.. _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 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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- 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 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