From 582fabf2b9599ebb9d213ec52bdee9a2a7c9dbc9 Mon Sep 17 00:00:00 2001
From: johnnyshields <27655+johnnyshields@users.noreply.github.com>
Date: Sat, 25 Nov 2023 03:53:21 +0900
Subject: [PATCH 1/4] Deprecate of GeoNear class and Criteria#max_scan methods
 which don't work on MongoDB Server 4.2+

---
 lib/mongoid/contextual/geo_near.rb         | 28 ++++++++++++++++++++++
 lib/mongoid/criteria/queryable/optional.rb |  2 ++
 2 files changed, 30 insertions(+)

diff --git a/lib/mongoid/contextual/geo_near.rb b/lib/mongoid/contextual/geo_near.rb
index f0bda793c1..5028519999 100644
--- a/lib/mongoid/contextual/geo_near.rb
+++ b/lib/mongoid/contextual/geo_near.rb
@@ -5,6 +5,8 @@ module Mongoid
   module Contextual
 
     # Represents a $geoNear database command instruction.
+    #
+    # @deprecated
     class GeoNear
       extend Forwardable
       include Enumerable
@@ -20,6 +22,8 @@ class GeoNear
       #   geo_near.average_distance
       #
       # @return [ Float | nil ] The average distance.
+      #
+      # @deprecated
       def average_distance
         average = stats["avgDistance"]
         (average.nil? || average.nan?) ? nil : average
@@ -34,6 +38,8 @@ def average_distance
       #   end
       #
       # @return [ Enumerator ] The enumerator.
+      #
+      # @deprecated
       def each
         if block_given?
           documents.each do |doc|
@@ -52,6 +58,8 @@ def each
       # @param [ Integer | Float ] value The distance multiplier.
       #
       # @return [ GeoNear ] The GeoNear wrapper.
+      #
+      # @deprecated
       def distance_multiplier(value)
         command[:distanceMultiplier] = value
         self
@@ -66,6 +74,8 @@ def distance_multiplier(value)
       #   operation on.
       # @param [ Criteria ] criteria The Mongoid criteria.
       # @param [ String ] near
+      #
+      # @deprecated
       def initialize(collection, criteria, near)
         @collection, @criteria = collection, criteria
         command[:geoNear] = collection.name.to_s
@@ -79,6 +89,8 @@ def initialize(collection, criteria, near)
       #   geo_near.inspect
       #
       # @return [ String ] The inspection string.
+      #
+      # @deprecated
       def inspect
 %Q{#<Mongoid::Contextual::GeoNear
   selector:   #{criteria.selector.inspect}
@@ -104,6 +116,8 @@ def inspect
       # @param [ Integer | Float ] value The maximum distance.
       #
       # @return [ GeoNear | Float ] The GeoNear command or the value.
+      #
+      # @deprecated
       def max_distance(value = nil)
         if value
           command[:maxDistance] = value
@@ -121,6 +135,8 @@ def max_distance(value = nil)
       # @param [ Integer | Float ] value The minimum distance.
       #
       # @return [ GeoNear ] The GeoNear command.
+      #
+      # @deprecated
       def min_distance(value)
         command[:minDistance] = value
         self
@@ -132,6 +148,8 @@ def min_distance(value)
       #   geo_near.spherical
       #
       # @return [ GeoNear ] The command.
+      #
+      # @deprecated
       def spherical
         command[:spherical] = true
         self
@@ -145,6 +163,8 @@ def spherical
       # @param [ true | false ] value Whether to return unique documents.
       #
       # @return [ GeoNear ] The command.
+      #
+      # @deprecated
       def unique(value = true)
         command[:unique] = value
         self
@@ -156,6 +176,8 @@ def unique(value = true)
       #   geo_near.execute
       #
       # @return [ Hash ] The raw output
+      #
+      # @deprecated
       def execute
         results
       end
@@ -166,6 +188,8 @@ def execute
       #   geo_near.stats
       #
       # @return [ Hash ] The stats from the command run.
+      #
+      # @deprecated
       def stats
         results["stats"]
       end
@@ -176,6 +200,8 @@ def stats
       #   geo_near.time
       #
       # @return [ Float ] The execution time.
+      #
+      # @deprecated
       def time
         stats["time"]
       end
@@ -186,6 +212,8 @@ def time
       #   geo_near.empty_and_chainable?
       #
       # @return [ true ] Always true.
+      #
+      # @deprecated
       def empty_and_chainable?
         true
       end
diff --git a/lib/mongoid/criteria/queryable/optional.rb b/lib/mongoid/criteria/queryable/optional.rb
index 45a7c8d18e..2f14f0ee79 100644
--- a/lib/mongoid/criteria/queryable/optional.rb
+++ b/lib/mongoid/criteria/queryable/optional.rb
@@ -93,6 +93,8 @@ def limit(value = nil)
         # @param [ Integer ] value The max number of documents to scan.
         #
         # @return [ Optional ] The cloned optional.
+        #
+        # @deprecated
         def max_scan(value = nil)
           option(value) { |options| options.store(:max_scan, value) }
         end

From de71de9642aa1921523ce3a4607ab75e2742723d Mon Sep 17 00:00:00 2001
From: johnnyshields <27655+johnnyshields@users.noreply.github.com>
Date: Sat, 25 Nov 2023 04:01:55 +0900
Subject: [PATCH 2/4] Add release notes

---
 docs/release-notes/mongoid-9.0.txt | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/docs/release-notes/mongoid-9.0.txt b/docs/release-notes/mongoid-9.0.txt
index 8209381ced..9bad0896fe 100644
--- a/docs/release-notes/mongoid-9.0.txt
+++ b/docs/release-notes/mongoid-9.0.txt
@@ -477,3 +477,17 @@ This section will be for smaller bug fixes and improvements:
 - Added support for serializing and deserializing BSON::ObjectId values
   when passed as ActiveJob arguments
   `MONGOID-5611 <https://jira.mongodb.org/browse/MONGOID-5611>`_.
+
+
+Newly deprecated functionality
+------------------------------
+
+The following functionality is deprecated and will be removed in a future
+Mongoid major version release:
+
+- The ``GeoNear`` class, which was `removed in MongoDB Server 4.2
+  <https://www.mongodb.com/docs/manual/release-notes/4.2-compatibility/#remove-support-for-the-geonear-command>`_.
+  Use the $geoNear aggregation pipeline stage instead.
+- The ``Criteria#max_scan` method, which was `removed in MongoDB Server 4.2
+  <https://www.mongodb.com/docs/manual/release-notes/4.2-compatibility/#remove-maxscan>`_.
+  Use the ``Criteria#max_time_ms`` method instead.

From e28ec42479d5cafc5fc9197465494f5676005862 Mon Sep 17 00:00:00 2001
From: Johnny Shields <27655+johnnyshields@users.noreply.github.com>
Date: Sat, 25 Nov 2023 13:39:04 +0900
Subject: [PATCH 3/4] Update geo_near.rb

---
 lib/mongoid/contextual/geo_near.rb | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/lib/mongoid/contextual/geo_near.rb b/lib/mongoid/contextual/geo_near.rb
index 5028519999..d51b0ff542 100644
--- a/lib/mongoid/contextual/geo_near.rb
+++ b/lib/mongoid/contextual/geo_near.rb
@@ -6,7 +6,8 @@ module Contextual
 
     # Represents a $geoNear database command instruction.
     #
-    # @deprecated
+    # @deprecated GeoNear is removed as of MongoDB Server 4.2. Please use the
+    #   $geoNear aggregation pipeline stage instead.
     class GeoNear
       extend Forwardable
       include Enumerable

From 8ce8cda9d1760df5e780043c626227569b247177 Mon Sep 17 00:00:00 2001
From: Johnny Shields <27655+johnnyshields@users.noreply.github.com>
Date: Sat, 25 Nov 2023 13:39:47 +0900
Subject: [PATCH 4/4] Update optional.rb

---
 lib/mongoid/criteria/queryable/optional.rb | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/mongoid/criteria/queryable/optional.rb b/lib/mongoid/criteria/queryable/optional.rb
index 2f14f0ee79..46a873ce96 100644
--- a/lib/mongoid/criteria/queryable/optional.rb
+++ b/lib/mongoid/criteria/queryable/optional.rb
@@ -94,7 +94,7 @@ def limit(value = nil)
         #
         # @return [ Optional ] The cloned optional.
         #
-        # @deprecated
+        # @deprecated max_scan is removed as of MongoDB Server 4.2. Please use max_time_ms instead.
         def max_scan(value = nil)
           option(value) { |options| options.store(:max_scan, value) }
         end