DOCSP-43092 Upgrade versions

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 <c-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 <c-upgrade>` section.
+
 Learn
 ------
 

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 <c-compatibility>` 
+  page.
+- Address any breaking changes between the current driver version
+  your application uses and your planned upgrade version in the
+  :ref:`Breaking Changes <c-breaking-changes>` section. To learn more about
+  {+mdb-server+} release compatibility changes, see the 
+  :ref:`Server Release Compatibility Changes <c-server-release-compatability-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. <Software_versioning#Schemes>` 
+    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. <https://www.mongodb.com/support-policy/legacy>`__
+
+.. _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 </release-notes>` in the {+mdb-server+} manual.