From 8c9d05f6eae7c0bfbc51edda334ed109057be1de Mon Sep 17 00:00:00 2001
From: rustagir <rea.rustagi@mongodb.com>
Date: Wed, 17 Jul 2024 16:13:14 -0400
Subject: [PATCH 01/14] DOCSP-41306: schema version trait

---
 docs/eloquent-models/model-class.txt          | 93 ++++++++++++++++++-
 .../eloquent-models/PlanetSchemaVersion.php   | 20 ++++
 2 files changed, 112 insertions(+), 1 deletion(-)
 create mode 100644 docs/includes/eloquent-models/PlanetSchemaVersion.php

diff --git a/docs/eloquent-models/model-class.txt b/docs/eloquent-models/model-class.txt
index f1d1fbdda..41b363b44 100644
--- a/docs/eloquent-models/model-class.txt
+++ b/docs/eloquent-models/model-class.txt
@@ -33,6 +33,8 @@ to {+odm-short+} models:
 - :ref:`laravel-model-customize` explains several model class customizations.
 - :ref:`laravel-model-pruning` shows how to periodically remove models that
   you no longer need.
+- :ref:`laravel-schema-versioning` shows how to implement model schema
+  versioning.
 
 .. _laravel-model-define:
 
@@ -67,7 +69,6 @@ This model is stored in the ``planets`` MongoDB collection.
 To learn how to specify the database name that your Laravel application uses,
 :ref:`laravel-quick-start-connect-to-mongodb`.
 
-
 .. _laravel-authenticatable-model:
 
 Extend the Authenticatable Model
@@ -333,3 +334,93 @@ models that the prune action deletes:
    :emphasize-lines: 5,10,12
    :dedent:
 
+.. _laravel-schema-versioning:
+
+Create a Versioned Model Schema
+-------------------------------
+
+You can implement a schema versioning pattern into your application by
+using the ``HasSchemaVersion`` trait on an Eloquent model. You might
+choose to implement a schema version to organize or standardize a
+collection that contains data with different schemas.
+
+.. tip::
+
+   To learn more about schema versioning, see the :manual:`Model Data for
+   Schema Versioning </tutorial/model-data-for-schema-versioning/>`
+   tutorial in the Server manual.
+
+To use this feature with models that use MongoDB as a database, add the
+``MongoDB\Laravel\Eloquent\HasSchemaVersion`` import to your model.
+Then, set the ``SCHEMA_VERSION`` constant to set the current schema
+version for your collection.
+
+When creating your model, you can define the ``migrateSchema()`` method
+to specify a migration to the current schema version upon saving a
+model.
+
+Schema Versioning Example
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The example class is defined with the following behavior:
+
+- Implements the ``HasSchemaVersion`` trait and sets the current
+  ``SCHEMA_VERSION`` to ``2``
+
+- Defines the ``migrateSchema()`` method to migrate models in which the
+  schema version is less than ``2`` to have a ``galaxy`` field that has a value
+  of ``'Milky Way'``
+
+.. literalinclude:: /includes/eloquent-models/PlanetSchemaVersion.php
+   :language: php
+   :emphasize-lines: 10,12,14
+   :dedent:
+
+When you save a model in which the ``schema_version`` field value is
+less than ``2``, Laravel adds the ``galaxy`` field and updates the schema
+version to the current version (``2``).
+
+The following code creates and saves instances of the ``Planet`` model that are
+not at the current schema version, then retrieves the planets from the
+collection to demonstrate the migration changes:
+
+.. io-code-block::
+   :copyable: true
+
+   .. input::
+      :language: php
+
+      $saturn = Planet::create([
+          'name' => 'Saturn',
+          'type' => 'gas',
+      ]);
+
+      $wasp = Planet::create([
+          'name' => 'WASP-39 b',
+          'type' => 'gas',
+          'schema_version' => 1,
+      ]);
+
+      $planets = Planet::where('type', 'gas')
+          ->get();
+
+   .. output::
+      :language: none
+      :visible: false
+
+      [
+        {
+          "_id": ...,
+          "name": "Saturn",
+          "type": "gas",
+          "galaxy": "Milky Way",
+          "schema_version": 2,
+        },
+        {
+          "_id": ...,
+          "name": "WASP-39 b",
+          "type": "gas",
+          "galaxy": "Milky Way",
+          "schema_version": 2,
+        }
+      ]
diff --git a/docs/includes/eloquent-models/PlanetSchemaVersion.php b/docs/includes/eloquent-models/PlanetSchemaVersion.php
new file mode 100644
index 000000000..daee89d11
--- /dev/null
+++ b/docs/includes/eloquent-models/PlanetSchemaVersion.php
@@ -0,0 +1,20 @@
+<?php
+
+namespace App\Models;
+
+use MongoDB\Laravel\Eloquent\HasSchemaVersion;
+use MongoDB\Laravel\Eloquent\Model;
+
+class Planet extends Model
+{
+    use HasSchemaVersion;
+
+    public const SCHEMA_VERSION = 2;
+
+    public function migrateSchema(int $fromVersion): void
+    {
+        if ($fromVersion < 2) {
+            $this->galaxy = 'Milky Way';
+        }
+    }
+}

From f3e67c78065822a8819d4ed27f24c5d5c0616b84 Mon Sep 17 00:00:00 2001
From: rustagir <rea.rustagi@mongodb.com>
Date: Wed, 17 Jul 2024 17:03:29 -0400
Subject: [PATCH 02/14] MW PR fixes 1

---
 docs/eloquent-models/model-class.txt | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/eloquent-models/model-class.txt b/docs/eloquent-models/model-class.txt
index 41b363b44..1cb044485 100644
--- a/docs/eloquent-models/model-class.txt
+++ b/docs/eloquent-models/model-class.txt
@@ -348,7 +348,7 @@ collection that contains data with different schemas.
 
    To learn more about schema versioning, see the :manual:`Model Data for
    Schema Versioning </tutorial/model-data-for-schema-versioning/>`
-   tutorial in the Server manual.
+   tutorial in the {+server-docs-name+}.
 
 To use this feature with models that use MongoDB as a database, add the
 ``MongoDB\Laravel\Eloquent\HasSchemaVersion`` import to your model.
@@ -376,12 +376,12 @@ The example class is defined with the following behavior:
    :emphasize-lines: 10,12,14
    :dedent:
 
-When you save a model in which the ``schema_version`` field value is
-less than ``2``, Laravel adds the ``galaxy`` field and updates the schema
-version to the current version (``2``).
+When you save a model in which the ``schema_version`` field is
+absent or the value is less than ``2``, Laravel adds the ``galaxy``
+field and updates the schema version to the current version (``2``).
 
-The following code creates and saves instances of the ``Planet`` model that are
-not at the current schema version, then retrieves the planets from the
+The following code inserts instances of the ``Planet`` model that are
+not at the current schema version, then retrieves the models from the
 collection to demonstrate the migration changes:
 
 .. io-code-block::

From bc1349ac82fa22d45b95f6d5508b61ee63aaed63 Mon Sep 17 00:00:00 2001
From: rustagir <rea.rustagi@mongodb.com>
Date: Thu, 18 Jul 2024 13:44:33 -0400
Subject: [PATCH 03/14] add test wip

---
 .../eloquent-models/SchemaVersionTest.php     | 40 +++++++++++++++++++
 1 file changed, 40 insertions(+)
 create mode 100644 docs/includes/eloquent-models/SchemaVersionTest.php

diff --git a/docs/includes/eloquent-models/SchemaVersionTest.php b/docs/includes/eloquent-models/SchemaVersionTest.php
new file mode 100644
index 000000000..b88efb7fe
--- /dev/null
+++ b/docs/includes/eloquent-models/SchemaVersionTest.php
@@ -0,0 +1,40 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Tests;
+
+use App\Models\Planet;
+use MongoDB\Laravel\Tests\TestCase;
+
+class SchemaVersionTest extends TestCase
+{
+    /**
+     * @runInSeparateProcess
+     * @preserveGlobalState disabled
+     */
+    public function testSchemaVersion(): void
+    {
+        require_once __DIR__ . '/PlanetSchemaVersion.php';
+
+        Planet::truncate();
+
+        $saturn = Planet::create([
+            'name' => 'Saturn',
+            'type' => 'gas',
+        ]);
+  
+        $wasp = Planet::create([
+            'name' => 'WASP-39 b',
+            'type' => 'gas',
+            'schema_version' => 1,
+        ]);
+
+        $planets = Planet::where('type', 'gas')
+            ->get();
+        echo 'After migration:\n' . $planets[0];
+
+        $this->assertCount(2, $planets);
+        $this->assertEquals(2, $planets[0]->schema_version);
+    }
+}

From 5543d5ceff42b90b6099deb7bcaca46c6c9de6d3 Mon Sep 17 00:00:00 2001
From: rustagir <rea.rustagi@mongodb.com>
Date: Thu, 18 Jul 2024 13:50:23 -0400
Subject: [PATCH 04/14] add tests

---
 .../eloquent-models/SchemaVersionTest.php         | 15 +++++++++++++--
 1 file changed, 13 insertions(+), 2 deletions(-)

diff --git a/docs/includes/eloquent-models/SchemaVersionTest.php b/docs/includes/eloquent-models/SchemaVersionTest.php
index b88efb7fe..634afe7d6 100644
--- a/docs/includes/eloquent-models/SchemaVersionTest.php
+++ b/docs/includes/eloquent-models/SchemaVersionTest.php
@@ -32,9 +32,20 @@ public function testSchemaVersion(): void
 
         $planets = Planet::where('type', 'gas')
             ->get();
-        echo 'After migration:\n' . $planets[0];
+
+        echo 'After migration:\n' . $planets;
 
         $this->assertCount(2, $planets);
-        $this->assertEquals(2, $planets[0]->schema_version);
+
+        $p1 = Planet::where('name', 'Saturn')
+            ->get();
+
+        $this->assertEquals(2, $p1->schema_version);
+
+        $p2 = Planet::where('name', 'WASP-39 b')
+            ->get();
+
+        $this->assertEquals(2, $p2->schema_version);
+        $this->assertEquals('Milky Way', $p2->galaxy);
     }
 }

From 16aff95c4329fa66491545a8dd098e1d3eb6b287 Mon Sep 17 00:00:00 2001
From: rustagir <rustagir@users.noreply.github.com>
Date: Thu, 18 Jul 2024 17:51:47 +0000
Subject: [PATCH 05/14] apply phpcbf formatting

---
 docs/includes/eloquent-models/SchemaVersionTest.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/includes/eloquent-models/SchemaVersionTest.php b/docs/includes/eloquent-models/SchemaVersionTest.php
index 634afe7d6..444171034 100644
--- a/docs/includes/eloquent-models/SchemaVersionTest.php
+++ b/docs/includes/eloquent-models/SchemaVersionTest.php
@@ -23,7 +23,7 @@ public function testSchemaVersion(): void
             'name' => 'Saturn',
             'type' => 'gas',
         ]);
-  
+
         $wasp = Planet::create([
             'name' => 'WASP-39 b',
             'type' => 'gas',

From e114452e7db69b9ea2f15e6c233afb32ebd7e24c Mon Sep 17 00:00:00 2001
From: rustagir <rea.rustagi@mongodb.com>
Date: Thu, 18 Jul 2024 14:38:28 -0400
Subject: [PATCH 06/14] JM tech review 1

---
 docs/eloquent-models/model-class.txt          | 36 +++++++++----------
 .../eloquent-models/PlanetSchemaVersion.php   |  2 ++
 .../eloquent-models/SchemaVersionTest.php     |  4 +--
 3 files changed, 20 insertions(+), 22 deletions(-)

diff --git a/docs/eloquent-models/model-class.txt b/docs/eloquent-models/model-class.txt
index 1cb044485..0f89d9fd9 100644
--- a/docs/eloquent-models/model-class.txt
+++ b/docs/eloquent-models/model-class.txt
@@ -352,8 +352,9 @@ collection that contains data with different schemas.
 
 To use this feature with models that use MongoDB as a database, add the
 ``MongoDB\Laravel\Eloquent\HasSchemaVersion`` import to your model.
-Then, set the ``SCHEMA_VERSION`` constant to set the current schema
-version for your collection.
+Then, set the ``SCHEMA_VERSION`` constant to ``1`` to set the first
+schema version on your collection. If your collection evolves to contain
+multiple schemas, you can change the value of the ``SCHEMA_VERSION`` constant.
 
 When creating your model, you can define the ``migrateSchema()`` method
 to specify a migration to the current schema version upon saving a
@@ -373,33 +374,28 @@ The example class is defined with the following behavior:
 
 .. literalinclude:: /includes/eloquent-models/PlanetSchemaVersion.php
    :language: php
-   :emphasize-lines: 10,12,14
+   :emphasize-lines: 10,12,16
    :dedent:
 
-When you save a model in which the ``schema_version`` field is
-absent or the value is less than ``2``, Laravel adds the ``galaxy``
+When you save a model that does not have a schema version specified,
+Laravel uses the latest schema version, but does not perform the
+migration.
+
+When you save a model in which the ``schema_version`` field value is
+less than ``2``, Laravel adds the ``galaxy``
 field and updates the schema version to the current version (``2``).
 
-The following code inserts instances of the ``Planet`` model that are
-not at the current schema version, then retrieves the models from the
-collection to demonstrate the migration changes:
+The following code inserts two instances of the ``Planet`` model, then
+retrieves the models from the collection to demonstrate the changes:
 
 .. io-code-block::
    :copyable: true
 
-   .. input::
+   .. input:: /includes/eloquent-models/SchemaVersionTest.php
       :language: php
-
-      $saturn = Planet::create([
-          'name' => 'Saturn',
-          'type' => 'gas',
-      ]);
-
-      $wasp = Planet::create([
-          'name' => 'WASP-39 b',
-          'type' => 'gas',
-          'schema_version' => 1,
-      ]);
+      :dedent:
+      :start-after: begin-schema-version
+      :end-before: end-schema-version
 
       $planets = Planet::where('type', 'gas')
           ->get();
diff --git a/docs/includes/eloquent-models/PlanetSchemaVersion.php b/docs/includes/eloquent-models/PlanetSchemaVersion.php
index daee89d11..cba4c155e 100644
--- a/docs/includes/eloquent-models/PlanetSchemaVersion.php
+++ b/docs/includes/eloquent-models/PlanetSchemaVersion.php
@@ -11,6 +11,8 @@ class Planet extends Model
 
     public const SCHEMA_VERSION = 2;
 
+    // Migrate documents with a lower schema version to the most current
+    // schema when inserting new data or retrieving from the database
     public function migrateSchema(int $fromVersion): void
     {
         if ($fromVersion < 2) {
diff --git a/docs/includes/eloquent-models/SchemaVersionTest.php b/docs/includes/eloquent-models/SchemaVersionTest.php
index 444171034..4aad86351 100644
--- a/docs/includes/eloquent-models/SchemaVersionTest.php
+++ b/docs/includes/eloquent-models/SchemaVersionTest.php
@@ -19,6 +19,7 @@ public function testSchemaVersion(): void
 
         Planet::truncate();
 
+        // begin-schema-version
         $saturn = Planet::create([
             'name' => 'Saturn',
             'type' => 'gas',
@@ -32,8 +33,7 @@ public function testSchemaVersion(): void
 
         $planets = Planet::where('type', 'gas')
             ->get();
-
-        echo 'After migration:\n' . $planets;
+        // end-schema-version
 
         $this->assertCount(2, $planets);
 

From e55af092332a8c4c6dedd5bf6d03446b9be8c63c Mon Sep 17 00:00:00 2001
From: rustagir <rea.rustagi@mongodb.com>
Date: Thu, 18 Jul 2024 14:40:30 -0400
Subject: [PATCH 07/14] error

---
 docs/eloquent-models/model-class.txt | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/docs/eloquent-models/model-class.txt b/docs/eloquent-models/model-class.txt
index 0f89d9fd9..7e43885b9 100644
--- a/docs/eloquent-models/model-class.txt
+++ b/docs/eloquent-models/model-class.txt
@@ -397,9 +397,6 @@ retrieves the models from the collection to demonstrate the changes:
       :start-after: begin-schema-version
       :end-before: end-schema-version
 
-      $planets = Planet::where('type', 'gas')
-          ->get();
-
    .. output::
       :language: none
       :visible: false

From 0ae0aee0e24a0bdc1348d1282798b7fd67e3268c Mon Sep 17 00:00:00 2001
From: rustagir <rea.rustagi@mongodb.com>
Date: Thu, 18 Jul 2024 14:46:01 -0400
Subject: [PATCH 08/14] comment style

---
 composer.json                                         | 3 ++-
 docs/includes/eloquent-models/PlanetSchemaVersion.php | 4 ++--
 2 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/composer.json b/composer.json
index af060bb3c..95ce98afa 100644
--- a/composer.json
+++ b/composer.json
@@ -41,7 +41,8 @@
         "mockery/mockery": "^1.4.4",
         "doctrine/coding-standard": "12.0.x-dev",
         "spatie/laravel-query-builder": "^5.6",
-        "phpstan/phpstan": "^1.10"
+        "phpstan/phpstan": "^1.10",
+        "squizlabs/php_codesniffer": "^3.0@dev"
     },
     "conflict": {
         "illuminate/bus": "< 10.37.2"
diff --git a/docs/includes/eloquent-models/PlanetSchemaVersion.php b/docs/includes/eloquent-models/PlanetSchemaVersion.php
index cba4c155e..1a9826ad7 100644
--- a/docs/includes/eloquent-models/PlanetSchemaVersion.php
+++ b/docs/includes/eloquent-models/PlanetSchemaVersion.php
@@ -11,8 +11,8 @@ class Planet extends Model
 
     public const SCHEMA_VERSION = 2;
 
-    // Migrate documents with a lower schema version to the most current
-    // schema when inserting new data or retrieving from the database
+    /* Migrate documents with a lower schema version to the most current
+    schema when inserting new data or retrieving from the database */
     public function migrateSchema(int $fromVersion): void
     {
         if ($fromVersion < 2) {

From 632297e93968c1d24b67392fd90a9d0d4299dd62 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Tamarelle?= <jerome@tamarelle.net>
Date: Thu, 18 Jul 2024 21:59:51 +0200
Subject: [PATCH 09/14] Fix test, expose 2 models, lock laravel version to
 avoid breaking change

---
 composer.json                                 |  5 ++--
 .../eloquent-models/PlanetSchemaVersion1.php  | 10 ++++++++
 ...maVersion.php => PlanetSchemaVersion2.php} |  8 +++++--
 .../eloquent-models/SchemaVersionTest.php     | 23 ++++++++++---------
 4 files changed, 30 insertions(+), 16 deletions(-)
 create mode 100644 docs/includes/eloquent-models/PlanetSchemaVersion1.php
 rename docs/includes/eloquent-models/{PlanetSchemaVersion.php => PlanetSchemaVersion2.php} (64%)

diff --git a/composer.json b/composer.json
index 95ce98afa..0f597724c 100644
--- a/composer.json
+++ b/composer.json
@@ -27,7 +27,7 @@
         "composer-runtime-api": "^2.0.0",
         "illuminate/cache": "^10.36|^11",
         "illuminate/container": "^10.0|^11",
-        "illuminate/database": "^10.30|^11",
+        "illuminate/database": "^10.30|>=11.0.0,<=11.16.0",
         "illuminate/events": "^10.0|^11",
         "illuminate/support": "^10.0|^11",
         "mongodb/mongodb": "^1.15"
@@ -41,8 +41,7 @@
         "mockery/mockery": "^1.4.4",
         "doctrine/coding-standard": "12.0.x-dev",
         "spatie/laravel-query-builder": "^5.6",
-        "phpstan/phpstan": "^1.10",
-        "squizlabs/php_codesniffer": "^3.0@dev"
+        "phpstan/phpstan": "^1.10"
     },
     "conflict": {
         "illuminate/bus": "< 10.37.2"
diff --git a/docs/includes/eloquent-models/PlanetSchemaVersion1.php b/docs/includes/eloquent-models/PlanetSchemaVersion1.php
new file mode 100644
index 000000000..c522b1935
--- /dev/null
+++ b/docs/includes/eloquent-models/PlanetSchemaVersion1.php
@@ -0,0 +1,10 @@
+<?php
+
+namespace App\Models;
+
+use MongoDB\Laravel\Eloquent\Model;
+
+class Planet extends Model
+{
+    protected $fillable = ['name', 'type', 'galaxy'];
+}
diff --git a/docs/includes/eloquent-models/PlanetSchemaVersion.php b/docs/includes/eloquent-models/PlanetSchemaVersion2.php
similarity index 64%
rename from docs/includes/eloquent-models/PlanetSchemaVersion.php
rename to docs/includes/eloquent-models/PlanetSchemaVersion2.php
index 1a9826ad7..ea426551e 100644
--- a/docs/includes/eloquent-models/PlanetSchemaVersion.php
+++ b/docs/includes/eloquent-models/PlanetSchemaVersion2.php
@@ -11,8 +11,12 @@ class Planet extends Model
 
     public const SCHEMA_VERSION = 2;
 
-    /* Migrate documents with a lower schema version to the most current
-    schema when inserting new data or retrieving from the database */
+    protected $fillable = ['name', 'type', 'galaxy'];
+
+    /**
+     * Migrate documents with a lower schema version to the most current
+     * schema when inserting new data or retrieving from the database.
+     */
     public function migrateSchema(int $fromVersion): void
     {
         if ($fromVersion < 2) {
diff --git a/docs/includes/eloquent-models/SchemaVersionTest.php b/docs/includes/eloquent-models/SchemaVersionTest.php
index 4aad86351..a2fe4f44b 100644
--- a/docs/includes/eloquent-models/SchemaVersionTest.php
+++ b/docs/includes/eloquent-models/SchemaVersionTest.php
@@ -15,35 +15,36 @@ class SchemaVersionTest extends TestCase
      */
     public function testSchemaVersion(): void
     {
-        require_once __DIR__ . '/PlanetSchemaVersion.php';
+        require_once __DIR__ . '/PlanetSchemaVersion2.php';
 
         Planet::truncate();
 
+        // Simulate a document stored with schema version 1, before schema update
+        Planet::insert([
+            [
+                'name' => 'WASP-39 b',
+                'type' => 'gas',
+                'schema_version' => 1,
+            ],
+        ]);
+
         // begin-schema-version
         $saturn = Planet::create([
             'name' => 'Saturn',
             'type' => 'gas',
         ]);
 
-        $wasp = Planet::create([
-            'name' => 'WASP-39 b',
-            'type' => 'gas',
-            'schema_version' => 1,
-        ]);
-
         $planets = Planet::where('type', 'gas')
             ->get();
         // end-schema-version
 
         $this->assertCount(2, $planets);
 
-        $p1 = Planet::where('name', 'Saturn')
-            ->get();
+        $p1 = Planet::where('name', 'Saturn')->first();
 
         $this->assertEquals(2, $p1->schema_version);
 
-        $p2 = Planet::where('name', 'WASP-39 b')
-            ->get();
+        $p2 = Planet::where('name', 'WASP-39 b')->first();
 
         $this->assertEquals(2, $p2->schema_version);
         $this->assertEquals('Milky Way', $p2->galaxy);

From 0d21446cfcaa77191eb22d44659cb4b800c8e7a3 Mon Sep 17 00:00:00 2001
From: rustagir <rea.rustagi@mongodb.com>
Date: Fri, 19 Jul 2024 13:10:49 -0400
Subject: [PATCH 10/14] JM tech review 2

---
 docs/eloquent-models/model-class.txt          | 24 ++++++++++++-------
 .../eloquent-models/PlanetSchemaVersion1.php  |  2 +-
 .../eloquent-models/SchemaVersionTest.php     |  6 +++--
 3 files changed, 21 insertions(+), 11 deletions(-)

diff --git a/docs/eloquent-models/model-class.txt b/docs/eloquent-models/model-class.txt
index 7e43885b9..124cc0b61 100644
--- a/docs/eloquent-models/model-class.txt
+++ b/docs/eloquent-models/model-class.txt
@@ -354,16 +354,26 @@ To use this feature with models that use MongoDB as a database, add the
 ``MongoDB\Laravel\Eloquent\HasSchemaVersion`` import to your model.
 Then, set the ``SCHEMA_VERSION`` constant to ``1`` to set the first
 schema version on your collection. If your collection evolves to contain
-multiple schemas, you can change the value of the ``SCHEMA_VERSION`` constant.
+multiple schemas, you can update the value of the ``SCHEMA_VERSION``
+constant in subsequent model classes.
 
 When creating your model, you can define the ``migrateSchema()`` method
 to specify a migration to the current schema version upon saving a
-model.
+model. In this method, you can specify the changes to make to an older
+model to update it to match the current schema version.
 
 Schema Versioning Example
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The example class is defined with the following behavior:
+In this sample situation, you are working with a collection that was
+first modeled by the following class:
+
+.. literalinclude:: /includes/eloquent-models/PlanetSchemaVersion1.php
+   :language: php
+   :dedent:
+
+Now, you want to implement a new schema version on the collection.
+You can define the new model class with the following behavior:
 
 - Implements the ``HasSchemaVersion`` trait and sets the current
   ``SCHEMA_VERSION`` to ``2``
@@ -372,14 +382,13 @@ The example class is defined with the following behavior:
   schema version is less than ``2`` to have a ``galaxy`` field that has a value
   of ``'Milky Way'``
 
-.. literalinclude:: /includes/eloquent-models/PlanetSchemaVersion.php
+.. literalinclude:: /includes/eloquent-models/PlanetSchemaVersion2.php
    :language: php
-   :emphasize-lines: 10,12,16
+   :emphasize-lines: 10,12,20
    :dedent:
 
 When you save a model that does not have a schema version specified,
-Laravel uses the latest schema version, but does not perform the
-migration.
+Laravel assumes that it follows the latest schema version.
 
 When you save a model in which the ``schema_version`` field value is
 less than ``2``, Laravel adds the ``galaxy``
@@ -406,7 +415,6 @@ retrieves the models from the collection to demonstrate the changes:
           "_id": ...,
           "name": "Saturn",
           "type": "gas",
-          "galaxy": "Milky Way",
           "schema_version": 2,
         },
         {
diff --git a/docs/includes/eloquent-models/PlanetSchemaVersion1.php b/docs/includes/eloquent-models/PlanetSchemaVersion1.php
index c522b1935..d4cbff71b 100644
--- a/docs/includes/eloquent-models/PlanetSchemaVersion1.php
+++ b/docs/includes/eloquent-models/PlanetSchemaVersion1.php
@@ -6,5 +6,5 @@
 
 class Planet extends Model
 {
-    protected $fillable = ['name', 'type', 'galaxy'];
+    protected $fillable = ['name', 'type'];
 }
diff --git a/docs/includes/eloquent-models/SchemaVersionTest.php b/docs/includes/eloquent-models/SchemaVersionTest.php
index a2fe4f44b..7bf54f679 100644
--- a/docs/includes/eloquent-models/SchemaVersionTest.php
+++ b/docs/includes/eloquent-models/SchemaVersionTest.php
@@ -19,7 +19,8 @@ public function testSchemaVersion(): void
 
         Planet::truncate();
 
-        // Simulate a document stored with schema version 1, before schema update
+        // begin-schema-version
+        // Simulates a document in the collection with schema version 1
         Planet::insert([
             [
                 'name' => 'WASP-39 b',
@@ -28,12 +29,13 @@ public function testSchemaVersion(): void
             ],
         ]);
 
-        // begin-schema-version
+        // Saves a document with no specified schema version
         $saturn = Planet::create([
             'name' => 'Saturn',
             'type' => 'gas',
         ]);
 
+        // Retrieves both models from the collection
         $planets = Planet::where('type', 'gas')
             ->get();
         // end-schema-version

From 5c984160fab0459b402b79417912f4415eeb160e Mon Sep 17 00:00:00 2001
From: rustagir <rea.rustagi@mongodb.com>
Date: Fri, 19 Jul 2024 13:14:21 -0400
Subject: [PATCH 11/14] fixes

---
 docs/eloquent-models/model-class.txt | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/docs/eloquent-models/model-class.txt b/docs/eloquent-models/model-class.txt
index 124cc0b61..b1fc98416 100644
--- a/docs/eloquent-models/model-class.txt
+++ b/docs/eloquent-models/model-class.txt
@@ -387,11 +387,11 @@ You can define the new model class with the following behavior:
    :emphasize-lines: 10,12,20
    :dedent:
 
-When you save a model that does not have a schema version specified,
-Laravel assumes that it follows the latest schema version.
+When you save or retrieve a model that does not have a schema version
+specified, Laravel assumes that it follows the latest schema version.
 
-When you save a model in which the ``schema_version`` field value is
-less than ``2``, Laravel adds the ``galaxy``
+When you save or retrieve a model in which the ``schema_version`` field
+value is less than ``2``, Laravel adds the ``galaxy``
 field and updates the schema version to the current version (``2``).
 
 The following code inserts two instances of the ``Planet`` model, then
@@ -413,15 +413,15 @@ retrieves the models from the collection to demonstrate the changes:
       [
         {
           "_id": ...,
-          "name": "Saturn",
+          "name": "WASP-39 b",
           "type": "gas",
+          "galaxy": "Milky Way",
           "schema_version": 2,
         },
         {
           "_id": ...,
-          "name": "WASP-39 b",
+          "name": "Saturn",
           "type": "gas",
-          "galaxy": "Milky Way",
           "schema_version": 2,
         }
       ]

From 9e5983ab75204e3ccd73841391774b53988ffcc5 Mon Sep 17 00:00:00 2001
From: rustagir <rea.rustagi@mongodb.com>
Date: Fri, 19 Jul 2024 13:17:33 -0400
Subject: [PATCH 12/14] revert database v

---
 composer.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/composer.json b/composer.json
index 0f597724c..af060bb3c 100644
--- a/composer.json
+++ b/composer.json
@@ -27,7 +27,7 @@
         "composer-runtime-api": "^2.0.0",
         "illuminate/cache": "^10.36|^11",
         "illuminate/container": "^10.0|^11",
-        "illuminate/database": "^10.30|>=11.0.0,<=11.16.0",
+        "illuminate/database": "^10.30|^11",
         "illuminate/events": "^10.0|^11",
         "illuminate/support": "^10.0|^11",
         "mongodb/mongodb": "^1.15"

From 7712c287bdaf1cfaec18d9fe3e47eb13be66c28a Mon Sep 17 00:00:00 2001
From: rustagir <rea.rustagi@mongodb.com>
Date: Fri, 19 Jul 2024 13:50:42 -0400
Subject: [PATCH 13/14] JM tech review 3

---
 docs/eloquent-models/model-class.txt | 23 +++++++++++++++--------
 1 file changed, 15 insertions(+), 8 deletions(-)

diff --git a/docs/eloquent-models/model-class.txt b/docs/eloquent-models/model-class.txt
index b1fc98416..b39252a6a 100644
--- a/docs/eloquent-models/model-class.txt
+++ b/docs/eloquent-models/model-class.txt
@@ -358,10 +358,16 @@ multiple schemas, you can update the value of the ``SCHEMA_VERSION``
 constant in subsequent model classes.
 
 When creating your model, you can define the ``migrateSchema()`` method
-to specify a migration to the current schema version upon saving a
+to specify a migration to the current schema version upon retrieving a
 model. In this method, you can specify the changes to make to an older
 model to update it to match the current schema version.
 
+When you save a model that does not have a schema version
+specified, Laravel assumes that it follows the latest schema version.
+When you retrieve a model that does not contain the ``schema_version``
+field, Laravel assumes that its schema version is ``0`` and performs the
+migration.
+
 Schema Versioning Example
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -387,15 +393,16 @@ You can define the new model class with the following behavior:
    :emphasize-lines: 10,12,20
    :dedent:
 
-When you save or retrieve a model that does not have a schema version
-specified, Laravel assumes that it follows the latest schema version.
+In the ``"WASP-39 b"`` document in the following code, the
+``schema_version`` field value is less than ``2``. When you retrieve the
+document, Laravel adds the ``galaxy`` field and updates the schema
+version to the current version, ``2``.
 
-When you save or retrieve a model in which the ``schema_version`` field
-value is less than ``2``, Laravel adds the ``galaxy``
-field and updates the schema version to the current version (``2``).
+The ``"Saturn"`` document does not contain the ``schema_version`` field,
+so Laravel assigns it the current schema version upon saving.
 
-The following code inserts two instances of the ``Planet`` model, then
-retrieves the models from the collection to demonstrate the changes:
+Finally, the code retrieves the models from the collection to
+demonstrate the changes:
 
 .. io-code-block::
    :copyable: true

From 342e2923a4207c1d61f4fbe5b6e2ca8e99417500 Mon Sep 17 00:00:00 2001
From: rustagir <rea.rustagi@mongodb.com>
Date: Fri, 19 Jul 2024 14:46:01 -0400
Subject: [PATCH 14/14] JM tech review 4

---
 docs/eloquent-models/model-class.txt | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/docs/eloquent-models/model-class.txt b/docs/eloquent-models/model-class.txt
index b39252a6a..ad5565abe 100644
--- a/docs/eloquent-models/model-class.txt
+++ b/docs/eloquent-models/model-class.txt
@@ -363,10 +363,10 @@ model. In this method, you can specify the changes to make to an older
 model to update it to match the current schema version.
 
 When you save a model that does not have a schema version
-specified, Laravel assumes that it follows the latest schema version.
-When you retrieve a model that does not contain the ``schema_version``
-field, Laravel assumes that its schema version is ``0`` and performs the
-migration.
+specified, the ``HasSchemaVersion`` trait assumes that it follows the
+latest schema version. When you retrieve a model that does not contain
+the ``schema_version`` field, the trait assumes that its schema version
+is ``0`` and performs the migration.
 
 Schema Versioning Example
 ~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -395,11 +395,11 @@ You can define the new model class with the following behavior:
 
 In the ``"WASP-39 b"`` document in the following code, the
 ``schema_version`` field value is less than ``2``. When you retrieve the
-document, Laravel adds the ``galaxy`` field and updates the schema
+document, {+odm-short+} adds the ``galaxy`` field and updates the schema
 version to the current version, ``2``.
 
 The ``"Saturn"`` document does not contain the ``schema_version`` field,
-so Laravel assigns it the current schema version upon saving.
+so {+odm-short+} assigns it the current schema version upon saving.
 
 Finally, the code retrieves the models from the collection to
 demonstrate the changes: