DOCSP-35933: Upgrade guide

Author: norareidy

docs/upgrade.txt

@@ -14,45 +14,32 @@ Upgrade ODM Version
 Overview
 --------
 
-On this page, you can learn how to upgrade {+odm-short+} to a new version. This page also 
-includes the changes you must make to your application to upgrade your ODM version 
-without losing functionality, if applicable.
-
-The PHP library uses `semantic versioning <https://semver.org/>`__. Upgrading
-to a new major version may require changes to your application.
+On this page, you can learn how to upgrade {+odm-short+} to a new major version.
+This page also includes the changes you must make to your application to upgrade
+your object-document mapper (ODM) version without losing functionality, if applicable.
 
 How to Upgrade
 --------------
 
 Before you upgrade, perform the following actions:
 
-- Ensure the new driver version is compatible with the {+mdb-server+} version
-  your application connects to and the version of Node.js that your
-  application runs on. See the :ref:`<node-compatibility>`
+- Ensure the new ODM version is compatible with the {+mdb-server+} version
+  your application connects to and the version of Laravel that your
+  application runs on. See the :ref:`<laravel-compatibility>`
   page for this information.
-- Address any breaking changes between the version of the driver
+- Address any breaking changes between the version of {+odm-short+} that
   your application currently uses and your planned upgrade version in the
-  :ref:`<node-breaking-changes>` section of this guide. To learn
-  more about the {+mdb-server+} release compatibility changes, see the 
-  :ref:`<node-server-support-changes>` section.
-
-.. tip::
+  :ref:`<laravel-breaking-changes>` section of this guide.
 
-   You can minimize the amount of changes that you need to make to your
-   application when upgrading driver versions by using the
-   :ref:`{+stable-api+} <nodejs-stable-api>`.
-
-To upgrade your driver version, run the following command in your application's 
+To upgrade your ODM version, run the following command in your application's 
 directory:
 
 .. code-block:: bash
 
-    npm install mongodb@{+version+}
+    composer require mongodb/laravel-mongodb:{+version+}
 
-To upgrade to a different version of the driver, replace the information after the
-``@`` symbol with your preferred version number. For more information about the
-``npm install`` command, see the `npm-install <https://docs.npmjs.com/cli/v10/commands/npm-install?v=true>`__ 
-npm documentation.
+To upgrade to a different version of the ODM, replace the information after
+``laravel-mongodb:`` with your preferred version number.
 
 .. _laravel-breaking-changes:
 
@@ -73,33 +60,43 @@ planned upgrade version.
 Version 4.x Breaking Changes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-- Laravel 10.x is required
+This ODM version introduces the following breaking changes:
+
+- Minimum Laravel version is now 10.0. For instructions on upgrading your Laravel version,
+  see the `Upgrade Guide <https://laravel.com/docs/10.x/upgrade>`__ in the Laravel
+  documentation.
 
-- Change dependency name in your composer.json to ``"mongodb/laravel-mongodb": "^4.0"``
-  and run ``composer update``
+- Dependency name is now ``"mongodb/laravel-mongodb"``. Ensure that the dependency
+  name in your ``composer.json`` file is ``"mongodb/laravel-mongodb": "^4.0"``. Then, run
+  ``composer update``.
 
-- Change namespace from ``Jenssegers\Mongodb\`` to ``MongoDB\Laravel\``
-  in your models and config
+- Namespace is now ``MongoDB\Laravel\``. Ensure that you change the namespace from ``Jenssegers\Mongodb\``
+  to ``MongoDB\Laravel\`` in your models and config files.
 
-- Remove support for non-Laravel projects
+- Removes support for non-Laravel projects.
 
-- Replace ``$dates`` with ``$casts`` in your models
+- Removes support for the ``$dates`` property. Ensure that you change all instances of ``$dates``
+  to ``$casts`` in your model files.
 
-- Call ``$model->save()`` after ``$model->unset('field')`` to persist the change
+- ``Model::unset($field)`` does not persist the change. Ensure that you follow all calls to
+  ``Model::unset($field)`` with ``Model::save()``.
 
-- Replace calls to ``Query\Builder::whereAll($column, $values)`` with
-  ``Query\Builder::where($column, 'all', $values)``
+- Removes the ``Query\Builder::whereAll($column, $values)`` method. Ensure that you replace all calls
+  to ``Query\Builder::whereAll($column, $values)`` with ``Query\Builder::where($column, 'all', $values)``.
 
-- ``Query\Builder::delete()`` doesn't accept ``limit()`` other than ``1`` or ``null``.
+- ``Query\Builder::delete()`` can only delete one or all documents. Ensure that you only pass a value 
+  of ``1`` or ``null`` to ``limit()``.
 
-- ``whereDate``, ``whereDay``, ``whereMonth``, ``whereYear``, ``whereTime``
-  now use MongoDB operators on date fields
+- ``whereDate()``, ``whereDay()``, ``whereMonth()``, ``whereYear()``, and ``whereTime()`` methods
+  now use MongoDB operators on date fields.
 
-- Replace ``Illuminate\Database\Eloquent\MassPrunable`` with ``MongoDB\Laravel\Eloquent\MassPrunable``
-  in your models
+- Adds the ``MongoDB\Laravel\Eloquent\MassPrunable`` trait. Ensure that you replace all instances of 
+  ``Illuminate\Database\Eloquent\MassPrunable`` with ``MongoDB\Laravel\Eloquent\MassPrunable``
+  in your models.
 
-- Remove calls to not-supported methods of ``Query\Builder``: ``toSql``,
+- Removes support for the ``Query\Builder``: ``toSql``,
   ``toRawSql``, ``whereColumn``, ``whereFullText``, ``groupByRaw``,
   ``orderByRaw``, ``unionAll``, ``union``, ``having``, ``havingRaw``,
   ``havingBetween``, ``whereIntegerInRaw``, ``orWhereIntegerInRaw``,
-  ``whereIntegerNotInRaw``, ``orWhereIntegerNotInRaw``.
+  ``whereIntegerNotInRaw``, and ``orWhereIntegerNotInRaw`` methods. Ensure that you remove 
+  all calls to these methods.