Deprecate #not() (without arguments)

Also, clean up and standardize the deprecation warnings a bit

Author: jamis

lib/mongoid/criteria/queryable/selectable.rb

@@ -491,23 +491,28 @@ def negating?
           !!negating
         end
 
-        # Negate the arguments, or the next selection if no arguments are given.
-        #
-        # @example Negate the next selection.
-        #   selectable.not.in(field: [ 1, 2 ])
+        # Negate the arguments.
         #
         # @example Add the $not criterion.
-        #   selectable.not(name: /Bob/)
+        #   Person.not(name: /Bob/)
         #
-        # @example Execute a $not in a where query.
-        #   selectable.where(:field.not => /Bob/)
+        # @example Negate a Criteria instance
+        #   Person.not(Person.where(...))
         #
         # @param [ [ Hash | Criteria ]... ] *criteria The key/value pair
         #   matches or Criteria objects to negate.
         #
         # @return [ Selectable ] The new selectable.
         def not(*criteria)
           if criteria.empty?
+            # @deprecated
+            Mongoid.deprecation_warning(
+              :not_sans_arguments,
+              'Calling `#not` without arguments is deprecated, and will be ' \
+              'removed in the next major version. Instead, pass the Hash or ' \
+              'Criteria instance to negate.',
+              caller_locations
+            )
             dup.tap { |query| query.negating = !query.negating }
           else
             criteria.compact.inject(clone) do |c, new_s|

lib/mongoid/deprecable.rb

@@ -7,6 +7,29 @@ module Mongoid
   #
   # @api private
   module Deprecable
+    # A Mongoid::Deprecation instance to use for reporting deprecations
+    def deprecator
+      @deprecator ||= Mongoid::Deprecation.new
+    end
+
+    # Resets all deprecation warnings. For use in tests.
+    def reset_deprecation_warnings!
+      DEPRECATION_WARNING_MUTEX.synchronize { @deprecation_warnings = {} }
+    end
+
+    # Emits a warning using the current deprecator. If the given warning (as
+    # identified by `id`) has already been issued previously, this is a no-op.
+    #
+    # @param [ Symbol ] id The unique identifier for this warning.
+    # @param [ String ] warning The warning message to emit.
+    # @param [ Array<Thread::Backtrace::Location> | nil ] callstack The backtrace at the call site.
+    def deprecation_warning(id, warning, callstack = nil)
+      site = callstack&.first
+      deprecation_warning_guard(id, site ? "#{site.path}:#{site.lineno}" : nil) do
+        deprecator.warn(warning, callstack)
+      end
+    end
+
     # Declares method(s) as deprecated.
     #
     # @example Deprecate a method.
@@ -25,8 +48,28 @@ module Deprecable
     # @param [ [ Symbol | Hash<Symbol, [ Symbol | String ]> ]... ] *method_descriptors
     #   The methods to deprecate, with optional replacement instructions.
     def deprecate(target_module, *method_descriptors)
-      @_deprecator ||= Mongoid::Deprecation.new
-      @_deprecator.deprecate_methods(target_module, *method_descriptors)
+      deprecator.deprecate_methods(target_module, *method_descriptors)
+    end
+
+    private
+
+    # The Mutex instance used to guard the deprecation warning flags.
+    DEPRECATION_WARNING_MUTEX = Mutex.new
+
+    # Wraps access to the warnings Hash in a synchronize block. If the given
+    # id+callsite has not been warned already, the method will yield to a block and then
+    # flag the id. Otherwise, it returns immediately.
+    def deprecation_warning_guard(id, callsite)
+      DEPRECATION_WARNING_MUTEX.synchronize do
+        @deprecation_warnings ||= {}
+
+        key = "#{id}:#{callsite}"
+        return if @deprecation_warnings.key?(key)
+
+        yield
+
+        @deprecation_warnings[key] = true
+      end
     end
   end
 end

lib/mongoid/timestamps/timeless.rb

@@ -7,10 +7,6 @@ module Timestamps
     module Timeless
       extend ActiveSupport::Concern
 
-      # Deprecator for the block-less form of the timeless API. Its removal
-      # horizon is computed automatically as (current major + 1).0.
-      DEPRECATION = Mongoid::Deprecation.new
-
       # Clears out the timeless option.
       #
       # @example Clear the timeless option.
@@ -132,9 +128,17 @@ module ClassMethods
         def timeless(&block)
           return Timeless.with_timeless(&block) if block
 
-          DEPRECATION.warn(
+          locations = caller_locations
+
+          # if this is called from the #timeless instance method, look up one
+          # level higher for the call site
+          locations.shift if locations[0].path == __FILE__
+
+          Mongoid.deprecation_warning(
+            :timeless_sans_block,
             'Calling #timeless without a block is deprecated; pass a block ' \
-            'instead, e.g. `record.timeless { record.save }`.'
+            'instead, e.g. `record.timeless { record.save }`.',
+            locations
           )
           counter = 0
           counter += 1 if self < Mongoid::Timestamps::Created

spec/mongoid/criteria/queryable/selectable_logical_spec.rb

@@ -1589,7 +1589,14 @@
   end
 
   describe '#not' do
+    # deprecated functionality
     context 'when provided no criterion' do
+      around do |example|
+        Mongoid.deprecator.silence do
+          example.run
+        end
+      end
+
       let(:selection) do
         query.not
       end

spec/mongoid/timestamps/timeless_spec.rb

@@ -12,7 +12,7 @@ class Chicken
         before_save :lay_timeless_egg
 
         def lay_timeless_egg
-          Egg.timeless.create!
+          Egg.timeless { Egg.create! }
         end
       end
 
@@ -30,7 +30,7 @@ class Egg
     context 'when timeless is used on one instance and then not used on another instance' do
       let!(:first_instance) do
         egg = Egg.create!
-        egg.timeless.save!
+        egg.timeless { egg.save! }
         egg
       end
 
@@ -60,7 +60,7 @@ class Egg
 
       context 'when the root executes timeless' do
         let!(:chicken) do
-          Chicken.timeless.create!
+          Chicken.timeless { Chicken.create! }
         end
 
         it 'creates the parent with a timestamp' do
@@ -80,7 +80,7 @@ class Egg
         end
 
         before do
-          document.timeless.save!
+          document.timeless { document.save! }
         end
 
         it 'does not set the created timestamp' do
@@ -108,7 +108,7 @@ class Egg
 
       context 'when used on the class' do
         let!(:document) do
-          Dokument.timeless.create!
+          Dokument.timeless { Dokument.create! }
         end
 
         it 'does not set the created timestamp' do
@@ -301,15 +301,17 @@ class TimelessFoo
   end
 
   describe 'deprecation of the block-less form' do
+    before { Mongoid.reset_deprecation_warnings! }
+
     let(:document) { Dokument.new }
 
     it 'warns when called on an instance without a block' do
-      expect(Mongoid.logger).to receive(:warn).with(/timeless/).and_call_original
+      expect(Mongoid.logger).to receive(:warn).with(/timeless/)
       document.timeless.save!
     end
 
     it 'warns when called on the class without a block' do
-      expect(Mongoid.logger).to receive(:warn).with(/timeless/).and_call_original
+      expect(Mongoid.logger).to receive(:warn).with(/timeless/)
       Dokument.timeless.create!
     end