From 9108d27e38fb8c7429e8ce32eb0d1127cf4059fe Mon Sep 17 00:00:00 2001
From: Nora Reidy <nora.reidy@mongodb.com>
Date: Fri, 11 Oct 2024 14:40:29 -0400
Subject: [PATCH] Docs changes v5.1 (#3174)

Adds raw() field conversions and Laravel Herd information
---
 docs/quick-start/download-and-install.txt | 13 +++++++++++++
 docs/upgrade.txt                          |  7 +++++++
 2 files changed, 20 insertions(+)

diff --git a/docs/quick-start/download-and-install.txt b/docs/quick-start/download-and-install.txt
index 5e9139ec8..f4e480ce5 100644
--- a/docs/quick-start/download-and-install.txt
+++ b/docs/quick-start/download-and-install.txt
@@ -28,6 +28,19 @@ Download and Install the Dependencies
 Complete the following steps to install and add the {+odm-short+} dependencies
 to a Laravel web application.
 
+.. tip::
+
+   As an alternative to the following installation steps, you can use Laravel Herd
+   to install MongoDB and configure a Laravel MongoDB development environment. For
+   more information about using Laravel Herd with MongoDB, see the following resources:
+   
+   - `Installing MongoDB via Herd Pro
+     <https://herd.laravel.com/docs/1/herd-pro-services/mongodb>`__ in the Herd
+     documentation
+   - `Laravel Herd Adds Native MongoDB Support
+     <https://www.mongodb.com/developer/products/mongodb/laravel-herd-native-support/>`__
+     in the MongoDB Developer Center
+
 .. procedure::
    :style: connected
 
diff --git a/docs/upgrade.txt b/docs/upgrade.txt
index 3032b8e1e..d730435fa 100644
--- a/docs/upgrade.txt
+++ b/docs/upgrade.txt
@@ -114,12 +114,19 @@ This library version introduces the following breaking changes:
 - In query results, the library converts BSON ``UTCDateTime`` objects to ``Carbon``
   date classes, applying the default timezone.
 
+  In v5.1, the library also performs this conversion to the ``Model::raw()``
+  method results before hydrating a Model instance.
+
 - ``id`` is an alias for the ``_id`` field in MongoDB documents, and the library
   automatically converts between ``id`` and ``_id`` when querying data. The query
   result object includes an ``id`` field to represent the document's ``_id`` field.
   Because of this behavior, you cannot have two separate ``id`` and ``_id`` fields
   in your documents.
 
+  In v5.1, the library also performs this conversion to the ``Model::raw()``
+  method results before hydrating a Model instance. When passing a complex query
+  filter, use the ``DB::where()`` method instead of ``Model::raw()``.
+
 - Removes support for the ``$collection`` property. The following code shows
   how to assign a MongoDB collection to a variable in your ``User`` class in
   older versions compared to v5.0: