Merge pull request #1559 from groyoh/deperecation_dsl

Deperecation dsl

CHANGELOG.md

@@ -29,6 +29,7 @@ Fixes:
 - [#1488](https://github.com/rails-api/active_model_serializers/pull/1488) Require ActiveSupport's string inflections (@nate00)
 
 Misc:
+- [#1559](https://github.com/rails-api/active_model_serializers/pull/1559) Add a deprecation DSL. (@bf4 @groyoh)
 - [#1543](https://github.com/rails-api/active_model_serializers/pull/1543) Add the changes missing from #1535. (@groyoh)
 - [#1535](https://github.com/rails-api/active_model_serializers/pull/1535) Move the adapter and adapter folder to
   active_model_serializers folder and changes the module namespace. (@domitian @bf4)

lib/active_model/serializer/adapter.rb

@@ -3,40 +3,20 @@ module ActiveModel
     # @deprecated Use ActiveModelSerializers::Adapter instead
     module Adapter
       class << self
-        def create(resource, options = {})
+        extend ActiveModelSerializers::Deprecate
-          warn_deprecation
-          ActiveModelSerializers::Adapter.create(resource, options)
-        end
 
-        def adapter_class(adapter)
+        def self.delegate_and_deprecate(method)
-          warn_deprecation
+          delegate method, to: ActiveModelSerializers::Adapter
-          ActiveModelSerializers::Adapter.adapter_class(adapter)
+          deprecate method, 'ActiveModelSerializers::Adapter.'
         end
+        private_class_method :delegate_and_deprecate
 
-        def adapter_map
+        delegate_and_deprecate :create
-          warn_deprecation
+        delegate_and_deprecate :adapter_class
-          ActiveModelSerializers::Adapter.adapter_map
+        delegate_and_deprecate :adapter_map
-        end
+        delegate_and_deprecate :adapters
-
+        delegate_and_deprecate :register
-        def adapters
+        delegate_and_deprecate :lookup
-          warn_deprecation
-          ActiveModelSerializers::Adapter.adapters
-        end
-
-        def register(name, klass = name)
-          warn_deprecation
-          ActiveModelSerializers::Adapter.register(name, klass)
-        end
-
-        def lookup(adapter)
-          warn_deprecation
-          ActiveModelSerializers::Adapter.lookup(adapter)
-        end
-
-        def warn_deprecation
-          warn "Calling deprecated #{name} (#{__FILE__}) from #{caller[1..3].join(', ')}. Please use ActiveModelSerializers::Adapter"
-        end
-        private :warn_deprecation
       end
 
       require 'active_model/serializer/adapter/base'

lib/active_model/serializer/adapter/attributes.rb

@@ -1,13 +1,14 @@
-require 'active_model_serializers/adapter/attributes'
-
 module ActiveModel
   class Serializer
     module Adapter
       class Attributes < DelegateClass(ActiveModelSerializers::Adapter::Attributes)
         def initialize(serializer, options = {})
-          warn "Calling deprecated #{self.class.name} (#{__FILE__}) from #{caller[0..2].join(', ')}. Please use #{self.class.name.sub('ActiveModel::Serializer', 'ActiveModelSerializers')}"
           super(ActiveModelSerializers::Adapter::Attributes.new(serializer, options))
         end
+        class << self
+          extend ActiveModelSerializers::Deprecate
+          deprecate :new, 'ActiveModelSerializers::Adapter::Json.'
+        end
       end
     end
   end

lib/active_model/serializer/adapter/base.rb

@@ -2,9 +2,9 @@ module ActiveModel
   class Serializer
     module Adapter
       class Base < DelegateClass(ActiveModelSerializers::Adapter::Base)
-        def self.inherited(base)
+        class << self
-          warn "Inheriting deprecated ActiveModel::Serializer::Adapter::Base in #{caller[0..2].join(', ')}. Please use ActiveModelSerializers::Adapter::Base"
+          extend ActiveModelSerializers::Deprecate
-          super
+          deprecate :inherited, 'ActiveModelSerializers::Adapter::Base.'
         end
 
         def initialize(serializer, options = {})

lib/active_model/serializer/adapter/json.rb

@@ -1,13 +1,14 @@
-require 'active_model_serializers/adapter/json'
-
 module ActiveModel
   class Serializer
     module Adapter
       class Json < DelegateClass(ActiveModelSerializers::Adapter::Json)
         def initialize(serializer, options = {})
-          warn "Calling deprecated #{self.class.name} (#{__FILE__}) from #{caller[0..2].join(', ')}. Please use #{self.class.name.sub('ActiveModel::Serializer', 'ActiveModelSerializers')}"
           super(ActiveModelSerializers::Adapter::Json.new(serializer, options))
         end
+        class << self
+          extend ActiveModelSerializers::Deprecate
+          deprecate :new, 'ActiveModelSerializers::Adapter::Json.new'
+        end
       end
     end
   end

lib/active_model/serializer/adapter/json_api.rb

@@ -1,13 +1,14 @@
-require 'active_model_serializers/adapter/json_api'
-
 module ActiveModel
   class Serializer
     module Adapter
       class JsonApi < DelegateClass(ActiveModelSerializers::Adapter::JsonApi)
         def initialize(serializer, options = {})
-          warn "Calling deprecated #{self.class.name} (#{__FILE__}) from #{caller[0..2].join(', ')}. Please use #{self.class.name.sub('ActiveModel::Serializer', 'ActiveModelSerializers')}"
           super(ActiveModelSerializers::Adapter::JsonApi.new(serializer, options))
         end
+        class << self
+          extend ActiveModelSerializers::Deprecate
+          deprecate :new, 'ActiveModelSerializers::Adapter::JsonApi.new'
+        end
       end
     end
   end

lib/active_model/serializer/adapter/null.rb

@@ -1,13 +1,14 @@
-require 'active_model_serializers/adapter/null'
-
 module ActiveModel
   class Serializer
     module Adapter
       class Null < DelegateClass(ActiveModelSerializers::Adapter::Null)
         def initialize(serializer, options = {})
-          warn "Calling deprecated #{self.class.name} (#{__FILE__}) from #{caller[0..2].join(', ')}. Please use #{self.class.name.sub('ActiveModel::Serializer', 'ActiveModelSerializers')}"
           super(ActiveModelSerializers::Adapter::Null.new(serializer, options))
         end
+        class << self
+          extend ActiveModelSerializers::Deprecate
+          deprecate :new, 'ActiveModelSerializers::Adapter::Null.new'
+        end
       end
     end
   end

lib/active_model/serializer/array_serializer.rb

@@ -1,9 +1,9 @@
 require 'active_model/serializer/collection_serializer'
 class ActiveModel::Serializer
   class ArraySerializer < CollectionSerializer
-    def initialize(*)
+    class << self
-      warn "Calling deprecated ArraySerializer in #{caller[0..2].join(', ')}. Please use CollectionSerializer"
+      extend ActiveModelSerializers::Deprecate
-      super
+      deprecate :new, 'ActiveModel::CollectionSerializer.'
     end
   end
 end

lib/active_model_serializers.rb

@@ -11,6 +11,7 @@ module ActiveModelSerializers
   autoload :Test
   autoload :Adapter
   autoload :JsonPointer
+  autoload :Deprecate
 
   class << self; attr_accessor :logger; end
   self.logger = ActiveSupport::TaggedLogging.new(ActiveSupport::Logger.new(STDOUT))
@@ -19,6 +20,15 @@ module ActiveModelSerializers
     ActiveModel::Serializer.config
   end
 
+  # The file name and line number of the caller of the caller of this method.
+  def self.location_of_caller
+    caller[1] =~ /(.*?):(\d+).*?$/i
+    file = Regexp.last_match(1)
+    lineno = Regexp.last_match(2).to_i
+
+    [file, lineno]
+  end
+
   require 'active_model/serializer/version'
   require 'active_model/serializer'
   require 'active_model/serializable_resource'

lib/active_model_serializers/deprecate.rb

@@ -0,0 +1,49 @@
+##
+# Provides a single method +deprecate+ to be used to declare when
+# something is going away.
+#
+#     class Legacy
+#       def self.klass_method
+#         # ...
+#       end
+#
+#       def instance_method
+#         # ...
+#       end
+#
+#       extend ActiveModelSerializers::Deprecate
+#       deprecate :instance_method, "ActiveModelSerializers::NewPlace#new_method"
+#
+#       class << self
+#         extend ActiveModelSerializers::Deprecate
+#         deprecate :klass_method, :none
+#       end
+#     end
+#
+# Adapted from https://github.com/rubygems/rubygems/blob/1591331/lib/rubygems/deprecate.rb
+module ActiveModelSerializers
+  module Deprecate
+    ##
+    # Simple deprecation method that deprecates +name+ by wrapping it up
+    # in a dummy method. It warns on each call to the dummy method
+    # telling the user of +replacement+ (unless +replacement+ is :none) that it is planned to go away.
+
+    def deprecate(name, replacement)
+      old = "_deprecated_#{name}"
+      alias_method old, name
+      class_eval do
+        define_method(name) do |*args, &block|
+          target = self.is_a?(Module) ? "#{self}." : "#{self.class}#"
+          msg = ["NOTE: #{target}#{name} is deprecated",
+                 replacement == :none ? ' with no replacement' : "; use #{replacement} instead",
+                 "\n#{target}#{name} called from #{ActiveModelSerializers.location_of_caller.join(":")}"
+                ]
+          warn "#{msg.join}."
+          send old, *args, &block
+        end
+      end
+    end
+
+    module_function :deprecate
+  end
+end

test/array_serializer_test.rb

@@ -11,7 +11,7 @@ module ActiveModel
           _, stderr = capture_io do
             super
           end
-          if stderr !~ /Calling deprecated ArraySerializer/
+          if stderr !~ /NOTE: ActiveModel::Serializer::ArraySerializer.new is deprecated/
             fail Minitest::Assertion, stderr
           end
         end
@@ -29,7 +29,7 @@ module ActiveModel
             serializer = ArraySerializer.new([comment, post])
             assert_equal 'comments', serializer.json_key
           end
-          assert_match(/Calling deprecated ArraySerializer/, stderr)
+          assert_match(/NOTE: ActiveModel::Serializer::ArraySerializer.new is deprecated/, stderr)
         end
       end
     end