DOCSP-41992 Upgrade versions

snooty.toml

@@ -25,8 +25,9 @@ toc_landing_pages = [
     "/databases-collections",
     "/write",
     "/indexes",
-    "/security"
-    "/data-formats"
+    "/security",
+    "/data-formats",
+    "/upgrade"
 ]
 
 sharedinclude_root =  "https://raw.githubusercontent.com/10gen/docs-shared/main/"

source/index.txt

@@ -22,6 +22,7 @@ MongoDB PHP Library
    /data-formats
    /compatibility
    /whats-new
+   /upgrade
    FAQ </faq>
    /reference
 

source/upgrade.txt

@@ -0,0 +1,123 @@
+.. _php-upgrade:
+
+=======================
+Upgrade Driver Versions
+=======================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: compatibility, backwards compatibility
+
+Overview
+--------
+
+On this page, you can learn how to upgrade your driver to a new version. This
+page also includes the changes you must make to your application when you 
+upgrade to a new version of the {+php-library+}.
+
+How to Upgrade
+--------------
+
+Before you upgrade, perform the following actions:
+
+- Ensure the new {+driver-short+} version is compatible with the {+mdb-server+} versions
+  your application connects to and the PHP version your
+  application compiles with. For version compatibility information, see the
+  :ref:`{+php-library+} Compatibility <php-compatibility>`
+  page.
+- Address any breaking changes between the driver version
+  your application is using and your planned upgrade version in the
+  :ref:`Breaking Changes <php-breaking-changes>` section.
+
+.. tip::
+
+   To ensure compatibility across {+mdb-server+} versions when
+   upgrading driver versions, use the :ref:`{+stable-api+} <php-stable-api>`.
+
+To upgrade your driver version, replace ``<version-number>`` with the version number 
+you want to upgrade to and run the following command in your application's 
+directory:
+
+.. code-block:: bash
+
+   composer require mongodb/mongodb:<version-number>
+
+Installation instructions for the ``mongodb`` extension may be found in the 
+:php:`PHP.net documentation <manual/en/mongodb.installation.php>`.
+
+.. _php-breaking-changes:
+
+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.
+
+For more information on release changes, see the release notes and associated 
+JIRA tickets for each release on `GitHub <https://github.com/mongodb/mongo-php-library/releases>`__.
+
+Version 1.20 Breaking Changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This driver version introduces the following breaking changes:
+
+- Drops support for {+mdb-server+} 3.6.
+
+- Deprecates iterators for database, collection, and index enumeration.
+
+Version 1.18 Breaking Changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This driver version introduces the following breaking changes:
+
+- Deprecates setting ``disableMD5`` to ``false`` when instantiating a Bucket due to 
+  deprecated MD5 encoding. The default value for the setting is now ``true``. 
+
+Version 1.17 Breaking Changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This driver version introduces the following breaking changes:
+
+- Upgrades the ``mongodb`` extension requirement to 1.17.0.
+
+- Requires PHP 7.4 or newer.
+
+- Removes aggregate compatibility logic, like the ``useCursor`` option, for 
+  {+mdb-server+} versions less than 3.6.
+
+Version 1.16 Breaking Changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This driver version introduces the following breaking changes:
+
+- Upgrades the ``mongodb`` extension requirement to 1.16.0.
+
+- Deprecates ``IndexInfo::isGeoHaystack()``. ``geoHaystack`` was removed in
+  {+mdb-server+} 5.0 and later.
+
+- Drops support for Composer 1.x.
+
+- Removes ``$server`` argument in ``Explainable::getCommandDocument``.
+
+- Removes ``getNonce`` command usage for {+mdb-server+} 6.2 and later.
+
+Version 1.15 Breaking Changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This driver version introduces the following breaking changes:
+
+- Upgrades the ``mongodb`` extension requirement to 1.15.0.