Merge pull request #5460 from chef/tm/deprecation_with_url

Core: Structure deprecations with additional metadata

65 files changed, 401 insertions, 154 deletions

diff --git a/lib-backcompat/chef/chef_fs/file_system/already_exists_error.rb b/lib-backcompat/chef/chef_fs/file_system/already_exists_error.rb
index 6d9973e8a4..75cebe5497 100644
--- a/lib-backcompat/chef/chef_fs/file_system/already_exists_error.rb
+++ b/lib-backcompat/chef/chef_fs/file_system/already_exists_error.rb
@@ -17,4 +17,4 @@
 #
 
 require "chef/chef_fs/file_system/exceptions"
-Chef.log_deprecation "Individual ChefFS error files are deprecated. Please require 'chef/chef_fs/file_system/exceptions' rather than 'chef/chef_fs/file_system/#{File.basename(__FILE__, ".rb")}'."
+Chef.deprecated :internal_api, "Individual ChefFS error files are deprecated. Please require 'chef/chef_fs/file_system/exceptions' rather than 'chef/chef_fs/file_system/#{File.basename(__FILE__, ".rb")}'."
diff --git a/lib-backcompat/chef/chef_fs/file_system/cookbook_frozen_error.rb b/lib-backcompat/chef/chef_fs/file_system/cookbook_frozen_error.rb
index 6d9973e8a4..75cebe5497 100644
--- a/lib-backcompat/chef/chef_fs/file_system/cookbook_frozen_error.rb
+++ b/lib-backcompat/chef/chef_fs/file_system/cookbook_frozen_error.rb
@@ -17,4 +17,4 @@
 #
 
 require "chef/chef_fs/file_system/exceptions"
-Chef.log_deprecation "Individual ChefFS error files are deprecated. Please require 'chef/chef_fs/file_system/exceptions' rather than 'chef/chef_fs/file_system/#{File.basename(__FILE__, ".rb")}'."
+Chef.deprecated :internal_api, "Individual ChefFS error files are deprecated. Please require 'chef/chef_fs/file_system/exceptions' rather than 'chef/chef_fs/file_system/#{File.basename(__FILE__, ".rb")}'."
diff --git a/lib-backcompat/chef/chef_fs/file_system/default_environment_cannot_be_modified_error.rb b/lib-backcompat/chef/chef_fs/file_system/default_environment_cannot_be_modified_error.rb
index 6d9973e8a4..75cebe5497 100644
--- a/lib-backcompat/chef/chef_fs/file_system/default_environment_cannot_be_modified_error.rb
+++ b/lib-backcompat/chef/chef_fs/file_system/default_environment_cannot_be_modified_error.rb
@@ -17,4 +17,4 @@
 #
 
 require "chef/chef_fs/file_system/exceptions"
-Chef.log_deprecation "Individual ChefFS error files are deprecated. Please require 'chef/chef_fs/file_system/exceptions' rather than 'chef/chef_fs/file_system/#{File.basename(__FILE__, ".rb")}'."
+Chef.deprecated :internal_api, "Individual ChefFS error files are deprecated. Please require 'chef/chef_fs/file_system/exceptions' rather than 'chef/chef_fs/file_system/#{File.basename(__FILE__, ".rb")}'."
diff --git a/lib-backcompat/chef/chef_fs/file_system/file_system_error.rb b/lib-backcompat/chef/chef_fs/file_system/file_system_error.rb
index 6d9973e8a4..75cebe5497 100644
--- a/lib-backcompat/chef/chef_fs/file_system/file_system_error.rb
+++ b/lib-backcompat/chef/chef_fs/file_system/file_system_error.rb
@@ -17,4 +17,4 @@
 #
 
 require "chef/chef_fs/file_system/exceptions"
-Chef.log_deprecation "Individual ChefFS error files are deprecated. Please require 'chef/chef_fs/file_system/exceptions' rather than 'chef/chef_fs/file_system/#{File.basename(__FILE__, ".rb")}'."
+Chef.deprecated :internal_api, "Individual ChefFS error files are deprecated. Please require 'chef/chef_fs/file_system/exceptions' rather than 'chef/chef_fs/file_system/#{File.basename(__FILE__, ".rb")}'."
diff --git a/lib-backcompat/chef/chef_fs/file_system/must_delete_recursively_error.rb b/lib-backcompat/chef/chef_fs/file_system/must_delete_recursively_error.rb
index 6d9973e8a4..75cebe5497 100644
--- a/lib-backcompat/chef/chef_fs/file_system/must_delete_recursively_error.rb
+++ b/lib-backcompat/chef/chef_fs/file_system/must_delete_recursively_error.rb
@@ -17,4 +17,4 @@
 #
 
 require "chef/chef_fs/file_system/exceptions"
-Chef.log_deprecation "Individual ChefFS error files are deprecated. Please require 'chef/chef_fs/file_system/exceptions' rather than 'chef/chef_fs/file_system/#{File.basename(__FILE__, ".rb")}'."
+Chef.deprecated :internal_api, "Individual ChefFS error files are deprecated. Please require 'chef/chef_fs/file_system/exceptions' rather than 'chef/chef_fs/file_system/#{File.basename(__FILE__, ".rb")}'."
diff --git a/lib-backcompat/chef/chef_fs/file_system/not_found_error.rb b/lib-backcompat/chef/chef_fs/file_system/not_found_error.rb
index 6d9973e8a4..75cebe5497 100644
--- a/lib-backcompat/chef/chef_fs/file_system/not_found_error.rb
+++ b/lib-backcompat/chef/chef_fs/file_system/not_found_error.rb
@@ -17,4 +17,4 @@
 #
 
 require "chef/chef_fs/file_system/exceptions"
-Chef.log_deprecation "Individual ChefFS error files are deprecated. Please require 'chef/chef_fs/file_system/exceptions' rather than 'chef/chef_fs/file_system/#{File.basename(__FILE__, ".rb")}'."
+Chef.deprecated :internal_api, "Individual ChefFS error files are deprecated. Please require 'chef/chef_fs/file_system/exceptions' rather than 'chef/chef_fs/file_system/#{File.basename(__FILE__, ".rb")}'."
diff --git a/lib-backcompat/chef/chef_fs/file_system/operation_failed_error.rb b/lib-backcompat/chef/chef_fs/file_system/operation_failed_error.rb
index 6d9973e8a4..75cebe5497 100644
--- a/lib-backcompat/chef/chef_fs/file_system/operation_failed_error.rb
+++ b/lib-backcompat/chef/chef_fs/file_system/operation_failed_error.rb
@@ -17,4 +17,4 @@
 #
 
 require "chef/chef_fs/file_system/exceptions"
-Chef.log_deprecation "Individual ChefFS error files are deprecated. Please require 'chef/chef_fs/file_system/exceptions' rather than 'chef/chef_fs/file_system/#{File.basename(__FILE__, ".rb")}'."
+Chef.deprecated :internal_api, "Individual ChefFS error files are deprecated. Please require 'chef/chef_fs/file_system/exceptions' rather than 'chef/chef_fs/file_system/#{File.basename(__FILE__, ".rb")}'."
diff --git a/lib-backcompat/chef/chef_fs/file_system/operation_not_allowed_error.rb b/lib-backcompat/chef/chef_fs/file_system/operation_not_allowed_error.rb
index 6d9973e8a4..75cebe5497 100644
--- a/lib-backcompat/chef/chef_fs/file_system/operation_not_allowed_error.rb
+++ b/lib-backcompat/chef/chef_fs/file_system/operation_not_allowed_error.rb
@@ -17,4 +17,4 @@
 #
 
 require "chef/chef_fs/file_system/exceptions"
-Chef.log_deprecation "Individual ChefFS error files are deprecated. Please require 'chef/chef_fs/file_system/exceptions' rather than 'chef/chef_fs/file_system/#{File.basename(__FILE__, ".rb")}'."
+Chef.deprecated :internal_api, "Individual ChefFS error files are deprecated. Please require 'chef/chef_fs/file_system/exceptions' rather than 'chef/chef_fs/file_system/#{File.basename(__FILE__, ".rb")}'."
diff --git a/lib-backcompat/chef/chef_fs/file_system/repository/chef_repository_file_system_entry.rb b/lib-backcompat/chef/chef_fs/file_system/repository/chef_repository_file_system_entry.rb
index eb2c3e8ff6..7668c6b174 100644
--- a/lib-backcompat/chef/chef_fs/file_system/repository/chef_repository_file_system_entry.rb
+++ b/lib-backcompat/chef/chef_fs/file_system/repository/chef_repository_file_system_entry.rb
@@ -1,6 +1,6 @@
 require "chef/chef_fs/file_system/repository/file_system_entry"
 
 module Chef::ChefFS::FileSystem::Repository
-  Chef.log_deprecation "Chef::ChefFS::FileSystem::Repository::ChefRepositoryFileSystemEntry is deprecated. Please use FileSystemEntry directly"
+  Chef.deprecated :internal_api, "Chef::ChefFS::FileSystem::Repository::ChefRepositoryFileSystemEntry is deprecated. Please use FileSystemEntry directly"
   ChefRepositoryFileSystemEntry = FileSystemEntry
 end
diff --git a/lib-backcompat/chef/chef_fs/file_system/repository/file_system_root_dir.rb b/lib-backcompat/chef/chef_fs/file_system/repository/file_system_root_dir.rb
index 8565ee6029..1c8bb87d72 100644
--- a/lib-backcompat/chef/chef_fs/file_system/repository/file_system_root_dir.rb
+++ b/lib-backcompat/chef/chef_fs/file_system/repository/file_system_root_dir.rb
@@ -24,7 +24,7 @@ class Chef
       module Repository
         class FileSystemRootDir < FileSystemEntry
           def initialize(file_path)
-            Chef.log_deprecation "Chef::ChefFS::FileSystem::Repository::FileSystemRootDir is deprecated."
+            Chef.deprecated :internal_api, "Chef::ChefFS::FileSystem::Repository::FileSystemRootDir is deprecated."
             super("", nil, file_path)
           end
         end
diff --git a/lib/chef/api_client.rb b/lib/chef/api_client.rb
index 3c1ef7a2b6..80e55c11a7 100644
--- a/lib/chef/api_client.rb
+++ b/lib/chef/api_client.rb
@@ -141,7 +141,7 @@ class Chef
     end
 
     def self.json_create(data)
-      Chef.log_deprecation("Auto inflation of JSON data is deprecated. Please use Chef::ApiClient#from_hash")
+      Chef.deprecated(:json_auto_inflate, "Auto inflation of JSON data is deprecated. Please use Chef::ApiClient#from_hash")
       from_hash(data)
     end
 
diff --git a/lib/chef/application.rb b/lib/chef/application.rb
index 7f15859c8f..e917a4eaf7 100644
--- a/lib/chef/application.rb
+++ b/lib/chef/application.rb
@@ -333,7 +333,7 @@ class Chef
 
     def emit_warnings
       if Chef::Config[:chef_gem_compile_time]
-        Chef.log_deprecation "setting chef_gem_compile_time to true is deprecated"
+        Chef.deprecated :chef_gem_compile_time, "setting chef_gem_compile_time to true is deprecated"
       end
     end
 
diff --git a/lib/chef/application/exit_code.rb b/lib/chef/application/exit_code.rb
index 6fec2524dd..b33085c95d 100644
--- a/lib/chef/application/exit_code.rb
+++ b/lib/chef/application/exit_code.rb
@@ -199,7 +199,7 @@ class Chef
 
         def notify_on_deprecation(message)
           begin
-            Chef.log_deprecation(message)
+            Chef.deprecated(:exit_code, message)
           rescue Chef::Exceptions::DeprecatedFeatureError
             # Have to rescue this, otherwise this unhandled error preempts
             # the current exit code assignment.
@@ -207,7 +207,7 @@ class Chef
         end
 
         def deprecation_warning
-          "Chef RFC 062 (https://github.com/chef/chef-rfc/master/rfc062-exit-status.md) defines the" \
+          "Chef RFC 062 (https://github.com/chef/chef-rfc/blob/master/rfc062-exit-status.md) defines the" \
           " exit codes that should be used with Chef.  Chef::Application::ExitCode defines valid exit codes"  \
           " In a future release, non-standard exit codes will be redefined as" \
           " GENERIC_FAILURE unless `exit_status` is set to `:disabled` in your client.rb."
diff --git a/lib/chef/chef_class.rb b/lib/chef/chef_class.rb
index 0bb15c03ca..8c766699fc 100644
--- a/lib/chef/chef_class.rb
+++ b/lib/chef/chef_class.rb
@@ -198,26 +198,35 @@ class Chef
     #
     # Emit a deprecation message.
     #
-    # @param message The message to send.
+    # @param type The message to send. This should be a symbol, referring to
+    #   a class defined in Chef::Deprecated
+    # @param message  An explicit message to display, rather than the generic one
+    #   associated with the deprecation.
     # @param location The location. Defaults to the caller who called you (since
     #   generally the person who triggered the check is the one that needs to be
     #   fixed).
     #
     # @example
-    #     Chef.deprecation("Deprecated!")
+    #     Chef.deprecated(:my_deprecation, message: "This is deprecated!")
     #
     # @api private this will likely be removed in favor of an as-yet unwritten
     #      `Chef.log`
-    def log_deprecation(message, location = nil)
+    def deprecated(type, message, location = nil)
       location ||= Chef::Log.caller_location
+      deprecation = Chef::Deprecated.create(type, message, location)
       # `run_context.events` is the primary deprecation target if we're in a
       # run. If we are not yet in a run, print to `Chef::Log`.
       if run_context && run_context.events
-        run_context.events.deprecation(message, location)
+        run_context.events.deprecation(deprecation, location)
       else
-        Chef::Log.deprecation(message, location)
+        Chef::Log.deprecation(deprecation, location)
       end
     end
+
+    def log_deprecation(message, location = nil)
+      location ||= Chef::Log.caller_location
+      Chef.deprecated(:generic, message, location)
+    end
   end
 
   # @api private Only for test dependency injection; not evenly implemented as yet.
diff --git a/lib/chef/client.rb b/lib/chef/client.rb
index c857da1b93..c064d33209 100644
--- a/lib/chef/client.rb
+++ b/lib/chef/client.rb
@@ -22,6 +22,7 @@ require "chef/config"
 require "chef/mixin/params_validate"
 require "chef/mixin/path_sanity"
 require "chef/log"
+require "chef/deprecated"
 require "chef/server_api"
 require "chef/api_client"
 require "chef/api_client/registration"
diff --git a/lib/chef/cookbook_version.rb b/lib/chef/cookbook_version.rb
index 8de9cb26dd..33226a7de5 100644
--- a/lib/chef/cookbook_version.rb
+++ b/lib/chef/cookbook_version.rb
@@ -54,12 +54,12 @@ class Chef
     attr_accessor :metadata_filenames
 
     def status=(new_status)
-      Chef.log_deprecation("Deprecated method `status' called. This method will be removed.")
+      Chef.deprecated(:internal_api, "Deprecated method `status' called. This method will be removed.")
       @status = new_status
     end
 
     def status
-      Chef.log_deprecation("Deprecated method `status' called. This method will be removed.")
+      Chef.deprecated(:internal_api, "Deprecated method `status' called. This method will be removed.")
       @status
     end
 
@@ -485,7 +485,7 @@ class Chef
     end
 
     def self.json_create(o)
-      Chef.log_deprecation("Auto inflation of JSON data is deprecated. Please use Chef::CookbookVersion#from_hash")
+      Chef.deprecated(:json_auto_inflate, "Auto inflation of JSON data is deprecated. Please use Chef::CookbookVersion#from_hash")
       from_hash(o)
     end
 
@@ -496,7 +496,7 @@ class Chef
     # @deprecated This method was used by the Ruby Chef Server and is no longer
     #   needed. There is no replacement.
     def generate_manifest_with_urls
-      Chef.log_deprecation("Deprecated method #generate_manifest_with_urls.")
+      Chef.deprecated(:internal_api, "Deprecated method #generate_manifest_with_urls.")
 
       rendered_manifest = manifest.dup
       COOKBOOK_SEGMENTS.each do |segment|
diff --git a/lib/chef/data_bag.rb b/lib/chef/data_bag.rb
index f107f98f28..7b32340f6a 100644
--- a/lib/chef/data_bag.rb
+++ b/lib/chef/data_bag.rb
@@ -80,7 +80,7 @@ class Chef
 
     # Create a Chef::Role from JSON
     def self.json_create(o)
-      Chef.log_deprecation("Auto inflation of JSON data is deprecated. Please use Chef::DataBag#from_hash")
+      Chef.deprecated(:json_auto_inflate, "Auto inflation of JSON data is deprecated. Please use Chef::DataBag#from_hash")
       from_hash(o)
     end
 
diff --git a/lib/chef/data_bag_item.rb b/lib/chef/data_bag_item.rb
index 568c511c44..83c568e6f3 100644
--- a/lib/chef/data_bag_item.rb
+++ b/lib/chef/data_bag_item.rb
@@ -141,7 +141,7 @@ class Chef
 
     # Create a Chef::DataBagItem from JSON
     def self.json_create(o)
-      Chef.log_deprecation("Auto inflation of JSON data is deprecated. Please use Chef::DataBagItem#from_hash")
+      Chef.deprecated(:json_auto_inflate, "Auto inflation of JSON data is deprecated. Please use Chef::DataBagItem#from_hash")
       from_hash(o)
     end
 
diff --git a/lib/chef/data_collector.rb b/lib/chef/data_collector.rb
index da7aeee3b8..82c41edfdc 100644
--- a/lib/chef/data_collector.rb
+++ b/lib/chef/data_collector.rb
@@ -274,7 +274,7 @@ class Chef
       # see EventDispatch::Base#deprecation
       # Append a received deprecation to the list of deprecations
       def deprecation(message, location = caller(2..2)[0])
-        add_deprecation(message, location)
+        add_deprecation(message.message, message.url, location)
       end
 
       private
@@ -410,8 +410,8 @@ class Chef
         @error_descriptions = discription_hash
       end
 
-      def add_deprecation(message, location)
-        @deprecations << { message: message, location: location }
+      def add_deprecation(message, url, location)
+        @deprecations << { message: message, url: url, location: location }
       end
 
       def create_resource_report(new_resource, action, current_resource = nil)
diff --git a/lib/chef/decorator/unchain.rb b/lib/chef/decorator/unchain.rb
index 8093c70f4c..b1e1f9fce1 100644
--- a/lib/chef/decorator/unchain.rb
+++ b/lib/chef/decorator/unchain.rb
@@ -44,10 +44,10 @@ class Chef
         if symbol == :to_ary
           merged_attributes.send(symbol, *args)
         elsif args.empty?
-          Chef.log_deprecation %q{method access to node attributes (node.foo.bar) is deprecated and will be removed in Chef 13, please use bracket syntax (node["foo"]["bar"])}
+          Chef.deprecated :attributes, %q{method access to node attributes (node.foo.bar) is deprecated and will be removed in Chef 13, please use bracket syntax (node["foo"]["bar"])}
           self[symbol]
         elsif symbol.to_s =~ /=$/
-          Chef.log_deprecation %q{method setting of node attributes (node.foo="bar") is deprecated and will be removed in Chef 13, please use bracket syntax (node["foo"]="bar")}
+          Chef.deprecated :attributes, %q{method setting of node attributes (node.foo="bar") is deprecated and will be removed in Chef 13, please use bracket syntax (node["foo"]="bar")}
           key_to_set = symbol.to_s[/^(.+)=$/, 1]
           self[key_to_set] = (args.length == 1 ? args[0] : args)
         else
diff --git a/lib/chef/deprecated.rb b/lib/chef/deprecated.rb
new file mode 100644
index 0000000000..de5090a48b
--- /dev/null
+++ b/lib/chef/deprecated.rb
@@ -0,0 +1,190 @@
+#--
+# Copyright:: Copyright 2016 Chef Software, Inc.
+# License:: Apache License, Version 2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+require "chef/mixin/convert_to_class_name"
+
+# Structured deprecations have a unique URL associated with them, which must exist before the deprecation is merged.
+class Chef
+  class Deprecated
+
+    class << self
+      include Chef::Mixin::ConvertToClassName
+
+      def create(type, message = nil, location = nil)
+        Chef::Deprecated.const_get(convert_to_class_name(type.to_s)).send(:new, message, location)
+      end
+    end
+
+    class Base
+      BASE_URL = "https://docs.chef.io/deprecations_"
+
+      attr_accessor :message, :location
+
+      def initialize(msg = nil, location = nil)
+        @message = msg if msg
+        @location = location if location
+      end
+
+      def link
+        "Please see #{url} for further details and information on how to correct this problem."
+      end
+
+      def url
+        "#{BASE_URL}#{target}"
+      end
+
+      # We know that the only time this gets called is by Chef::Log.deprecation,
+      # so special case
+      def <<(location)
+        @location = location
+      end
+
+      def inspect
+        "#{message} (CHEF-#{id})#{location}.\n#{link}"
+      end
+
+      def id
+        raise NotImplementedError, "subclasses of Chef::Deprecated::Base should define #id with a unique number"
+      end
+
+      def target
+        raise NotImplementedError, "subclasses of Chef::Deprecated::Base should define #target"
+      end
+    end
+
+    class JsonAutoInflate < Base
+      def id
+        1
+      end
+
+      def target
+        "json_auto_inflate.html"
+      end
+    end
+
+    class ExitCode < Base
+      def id
+        2
+      end
+
+      def target
+        "exit_code.html"
+      end
+    end
+
+    class ChefGemCompileTime < Base
+      def id
+        3
+      end
+
+      def target
+        "chef_gem_compile_time.html"
+      end
+    end
+
+    class Attributes < Base
+      def id
+        4
+      end
+
+      def target
+        "attributes.html"
+      end
+    end
+
+    class CustomResource < Base
+      def id
+        5
+      end
+
+      def target
+        "custom_resource_cleanups.html"
+      end
+    end
+
+    class EasyInstall < Base
+      def id
+        6
+      end
+
+      def target
+        "easy_install.html"
+      end
+    end
+
+    class VerifyFile < Base
+      def id
+        7
+      end
+
+      def target
+        "verify_file.html"
+      end
+    end
+
+    class SupportsProperty < Base
+      def id
+        8
+      end
+
+      def target
+        "supports_property.html"
+      end
+    end
+
+    class ChefRest < Base
+      def id
+        9
+      end
+
+      def target
+        "chef_rest.html"
+      end
+    end
+
+    class ResourceCloning < Base
+      def id
+        3694
+      end
+
+      def target
+        "resource_cloning.html"
+      end
+    end
+
+    class InternalApi < Base
+      def id
+        0
+      end
+
+      def target
+        "internal_api.html"
+      end
+    end
+
+    class Generic < Base
+      def url
+        "https://docs.chef.io/chef_deprecations_client.html"
+      end
+
+      def inspect
+        "#{message}\nThis is a generic error message and should be updated to have a proper deprecation class. #{location}\nPlease see #{url} for an overview of Chef deprecations."
+      end
+    end
+
+  end
+end
diff --git a/lib/chef/deprecation/provider/remote_directory.rb b/lib/chef/deprecation/provider/remote_directory.rb
index 5e5188f28b..9b442651d7 100644
--- a/lib/chef/deprecation/provider/remote_directory.rb
+++ b/lib/chef/deprecation/provider/remote_directory.rb
@@ -22,7 +22,7 @@ class Chef
       module RemoteDirectory
 
         def directory_root_in_cookbook_cache
-          Chef.log_deprecation "the Chef::Provider::RemoteDirectory#directory_root_in_cookbook_cache method is deprecated"
+          Chef.deprecated :internal_api, "the Chef::Provider::RemoteDirectory#directory_root_in_cookbook_cache method is deprecated"
 
           @directory_root_in_cookbook_cache ||=
             begin
diff --git a/lib/chef/deprecation/warnings.rb b/lib/chef/deprecation/warnings.rb
index 411e95ea39..f5feb91063 100644
--- a/lib/chef/deprecation/warnings.rb
+++ b/lib/chef/deprecation/warnings.rb
@@ -23,10 +23,9 @@ class Chef
       def add_deprecation_warnings_for(method_names)
         method_names.each do |name|
           define_method(name) do |*args|
-            message = []
-            message << "Method '#{name}' of '#{self.class}' is deprecated. It will be removed in Chef 13."
-            message << "Please update your cookbooks accordingly."
-            Chef.log_deprecation(message)
+            message = "Method '#{name}' of '#{self.class}' is deprecated. It will be removed in Chef 13."
+            message << " Please update your cookbooks accordingly."
+            Chef.deprecated(:internal_api, message)
             super(*args)
           end
         end
diff --git a/lib/chef/dsl/method_missing.rb b/lib/chef/dsl/method_missing.rb
index 51c3eac606..2917a54ee8 100644
--- a/lib/chef/dsl/method_missing.rb
+++ b/lib/chef/dsl/method_missing.rb
@@ -37,7 +37,7 @@ class Chef
         # method_missing manually. Not a fan. Not. A. Fan.
         #
         if respond_to?(method_symbol)
-          Chef.log_deprecation("Calling method_missing(#{method_symbol.inspect}) directly is deprecated in Chef 12 and will be removed in Chef 13. Use public_send() or send() instead.")
+          Chef.deprecated(:internal_api, "Calling method_missing(#{method_symbol.inspect}) directly is deprecated in Chef 12 and will be removed in Chef 13. Use public_send() or send() instead.")
           return send(method_symbol, *args, &block)
         end
 
@@ -46,7 +46,7 @@ class Chef
         # never called.  DEPRECATED.
         #
         if run_context.definitions.has_key?(method_symbol.to_sym)
-          Chef.log_deprecation("Definition #{method_symbol} (#{run_context.definitions[method_symbol.to_sym]}) was added to the run_context without calling Chef::DSL::Definitions.add_definition(#{method_symbol.to_sym.inspect}).  This will become required in Chef 13.")
+          Chef.deprecated(:internal_api, "Definition #{method_symbol} (#{run_context.definitions[method_symbol.to_sym]}) was added to the run_context without calling Chef::DSL::Definitions.add_definition(#{method_symbol.to_sym.inspect}).  This will become required in Chef 13.")
           Chef::DSL::Definitions.add_definition(method_symbol)
           return send(method_symbol, *args, &block)
         end
diff --git a/lib/chef/dsl/resources.rb b/lib/chef/dsl/resources.rb
index 7bbfeb2914..0d654316d8 100644
--- a/lib/chef/dsl/resources.rb
+++ b/lib/chef/dsl/resources.rb
@@ -36,14 +36,14 @@ class Chef
         begin
           module_eval(<<-EOM, __FILE__, __LINE__ + 1)
             def #{dsl_name}(*args, &block)
-              Chef.log_deprecation("Cannot create resource #{dsl_name} with more than one argument. All arguments except the name (\#{args[0].inspect}) will be ignored. This will cause an error in Chef 13. Arguments: \#{args}") if args.size > 1
+              Chef.deprecated(:internal_api, "Cannot create resource #{dsl_name} with more than one argument. All arguments except the name (\#{args[0].inspect}) will be ignored. This will cause an error in Chef 13. Arguments: \#{args}") if args.size > 1
               declare_resource(#{dsl_name.inspect}, args[0], caller[0], &block)
             end
           EOM
         rescue SyntaxError
           # Handle the case where dsl_name has spaces, etc.
           define_method(dsl_name.to_sym) do |*args, &block|
-            Chef.log_deprecation("Cannot create resource #{dsl_name} with more than one argument. All arguments except the name (#{args[0].inspect}) will be ignored. This will cause an error in Chef 13. Arguments: #{args}") if args.size > 1
+            Chef.deprecated(:internal_api, "Cannot create resource #{dsl_name} with more than one argument. All arguments except the name (#{args[0].inspect}) will be ignored. This will cause an error in Chef 13. Arguments: #{args}") if args.size > 1
             declare_resource(dsl_name, args[0], caller[0], &block)
           end
         end
diff --git a/lib/chef/environment.rb b/lib/chef/environment.rb
index 32ebde6f4f..c41df768b9 100644
--- a/lib/chef/environment.rb
+++ b/lib/chef/environment.rb
@@ -217,7 +217,7 @@ class Chef
     end
 
     def self.json_create(o)
-      Chef.log_deprecation("Auto inflation of JSON data is deprecated. Please use Chef::Environment#from_hash")
+      Chef.deprecated(:json_auto_inflate, "Auto inflation of JSON data is deprecated. Please use Chef::Environment#from_hash")
       from_hash(o)
     end
 
diff --git a/lib/chef/formatters/base.rb b/lib/chef/formatters/base.rb
index 536bf72e02..2fbe00862c 100644
--- a/lib/chef/formatters/base.rb
+++ b/lib/chef/formatters/base.rb
@@ -213,7 +213,17 @@ class Chef
       end
 
       def deprecation(message, location = caller(2..2)[0])
-        Chef::Log.deprecation("#{message} at #{location}")
+        out = if is_structured_deprecation?(message)
+                message.inspect
+              else
+                "#{message} at #{location}"
+              end
+
+        Chef::Log.deprecation(out)
+      end
+
+      def is_structured_deprecation?(deprecation)
+        deprecation.kind_of?(Chef::Deprecated::Base)
       end
 
       def is_formatter?
diff --git a/lib/chef/formatters/doc.rb b/lib/chef/formatters/doc.rb
index 7dbbf1d948..0c51cc2cfb 100644
--- a/lib/chef/formatters/doc.rb
+++ b/lib/chef/formatters/doc.rb
@@ -61,9 +61,10 @@ class Chef
         if !deprecations.empty?
           puts_line ""
           puts_line "Deprecated features used!"
-          deprecations.each do |message, locations|
+          deprecations.each do |message, details|
+            locations = details[:locations]
             if locations.size == 1
-              puts_line "  #{message} at #{locations.size} location:"
+              puts_line "  #{message} at 1 location:"
             else
               puts_line "  #{message} at #{locations.size} locations:"
             end
@@ -74,6 +75,9 @@ class Chef
                 prefix = "      "
               end
             end
+            unless details[:url].nil?
+              puts_line "   See #{details[:url]} for further details."
+            end
           end
           puts_line ""
         end
@@ -416,8 +420,13 @@ class Chef
         end
 
         # Save deprecations to the screen until the end
-        deprecations[message] ||= Set.new
-        deprecations[message] << location
+        if is_structured_deprecation?(message)
+          url = message.url
+          message = message.message
+        end
+
+        deprecations[message] ||= { url: url, locations: Set.new }
+        deprecations[message][:locations] << location
       end
 
       def indent
diff --git a/lib/chef/key.rb b/lib/chef/key.rb
index 38822e8b26..d19ff433a3 100644
--- a/lib/chef/key.rb
+++ b/lib/chef/key.rb
@@ -223,7 +223,7 @@ class Chef
       end
 
       def json_create(json)
-        Chef.log_deprecation("Auto inflation of JSON data is deprecated. Please use Chef::Key#from_json or one of the load_by methods.")
+        Chef.deprecated(:json_auto_inflate, "Auto inflation of JSON data is deprecated. Please use Chef::Key#from_json or one of the load_by methods.")
         Chef::Key.from_json(json)
       end
 
diff --git a/lib/chef/knife/core/subcommand_loader.rb b/lib/chef/knife/core/subcommand_loader.rb
index e617b39ded..30a438b780 100644
--- a/lib/chef/knife/core/subcommand_loader.rb
+++ b/lib/chef/knife/core/subcommand_loader.rb
@@ -51,7 +51,7 @@ class Chef
           Chef::Log.debug("Using autogenerated hashed command manifest #{plugin_manifest_path}")
           Knife::SubcommandLoader::HashedCommandLoader.new(chef_config_dir, plugin_manifest)
         elsif custom_manifest?
-          Chef.log_deprecation("Using custom manifest #{plugin_manifest_path} is deprecated. Please use a `knife rehash` autogenerated manifest instead.")
+          Chef.deprecated(:internal_api, "Using custom manifest #{plugin_manifest_path} is deprecated. Please use a `knife rehash` autogenerated manifest instead.")
           Knife::SubcommandLoader::CustomManifestLoader.new(chef_config_dir, plugin_manifest)
         else
           Knife::SubcommandLoader::GemGlobLoader.new(chef_config_dir)
@@ -90,7 +90,7 @@ class Chef
         # Deprecated and un-used instance variable.
         @env = env
         unless env.nil?
-          Chef.log_deprecation("The env argument to Chef::Knife::SubcommandLoader is deprecated. If you are using env to inject/mock HOME, consider mocking Chef::Util::PathHelper.home instead.")
+          Chef.deprecated(:internal_api, "The env argument to Chef::Knife::SubcommandLoader is deprecated. If you are using env to inject/mock HOME, consider mocking Chef::Util::PathHelper.home instead.")
         end
       end
 
@@ -154,7 +154,7 @@ class Chef
       # to get in the past.
       #
       def subcommand_files
-        Chef.log_deprecation "Using Chef::Knife::SubcommandLoader directly is deprecated.
+        Chef.deprecated :internal_api, "Using Chef::Knife::SubcommandLoader directly is deprecated.
 Please use Chef::Knife::SubcommandLoader.for_config(chef_config_dir, env)"
         @subcommand_files ||= if Chef::Knife::SubcommandLoader.plugin_manifest?
                                 Chef::Knife::SubcommandLoader::CustomManifestLoader.new(chef_config_dir, env).subcommand_files
diff --git a/lib/chef/knife/core/ui.rb b/lib/chef/knife/core/ui.rb
index 67e431f1a7..0e07dd704f 100644
--- a/lib/chef/knife/core/ui.rb
+++ b/lib/chef/knife/core/ui.rb
@@ -186,7 +186,7 @@ class Chef
 
         if parse_output
           if object_class.nil?
-            Chef.log_deprecation("Auto inflation of JSON data is deprecated. Please pass in the class to inflate or use #edit_hash")
+            Chef.deprecated(:json_auto_inflate, "Auto inflation of JSON data is deprecated. Please pass in the class to inflate or use #edit_hash")
             Chef::JSONCompat.from_json(output)
           else
             object_class.from_hash(Chef::JSONCompat.parse(output))
diff --git a/lib/chef/log.rb b/lib/chef/log.rb
index ac2baeb9d1..10c9f0f20d 100644
--- a/lib/chef/log.rb
+++ b/lib/chef/log.rb
@@ -58,7 +58,7 @@ class Chef
       end
       if Chef::Config[:treat_deprecation_warnings_as_errors]
         error(msg, &block)
-        raise Chef::Exceptions::DeprecatedFeatureError.new(msg)
+        raise Chef::Exceptions::DeprecatedFeatureError.new(msg.inspect)
       else
         warn(msg, &block)
       end
diff --git a/lib/chef/mixin/deprecation.rb b/lib/chef/mixin/deprecation.rb
index 0f059a215f..14414036e7 100644
--- a/lib/chef/mixin/deprecation.rb
+++ b/lib/chef/mixin/deprecation.rb
@@ -65,7 +65,7 @@ class Chef
         end
 
         def method_missing(method_name, *args, &block)
-          log_deprecation_msg(caller[0..3])
+          deprecated_msg(caller[0..3])
           @target.send(method_name, *args, &block)
         end
 
@@ -75,7 +75,7 @@ class Chef
 
         private
 
-        def log_deprecation_msg(*called_from)
+        def deprecated_msg(*called_from)
           called_from = called_from.flatten
           log("Accessing #{@ivar_name} by the variable @#{@ivar_name} is deprecated. Support will be removed in a future release.")
           log("Please update your cookbooks to use #{@ivar_name} in place of @#{@ivar_name}. Accessed from:")
@@ -101,20 +101,14 @@ class Chef
 
       def deprecated_attr_reader(name, alternative, level = :warn)
         define_method(name) do
-          Chef.log_deprecation("#{self.class}.#{name} is deprecated. Support will be removed in a future release.")
-          Chef.log_deprecation(alternative)
-          Chef.log_deprecation("Called from:")
-          caller[0..3].each { |c| Chef.log_deprecation(c) }
+          Chef.deprecated(:internal_api, "#{self.class}.#{name} is deprecated. Support will be removed in a future release. #{alternative}")
           instance_variable_get("@#{name}")
         end
       end
 
       def deprecated_attr_writer(name, alternative, level = :warn)
         define_method("#{name}=") do |value|
-          Chef.log_deprecation("Writing to #{self.class}.#{name} with #{name}= is deprecated. Support will be removed in a future release.")
-          Chef.log_deprecation(alternative)
-          Chef.log_deprecation("Called from:")
-          caller[0..3].each { |c| Chef.log_deprecation(c) }
+          Chef.deprecated(:internal_api, "Writing to #{self.class}.#{name} with #{name}= is deprecated. Support will be removed in a future release. #{alternative}")
           instance_variable_set("@#{name}", value)
         end
       end
diff --git a/lib/chef/mixin/shell_out.rb b/lib/chef/mixin/shell_out.rb
index d8607c8de7..cc2bf085e9 100644
--- a/lib/chef/mixin/shell_out.rb
+++ b/lib/chef/mixin/shell_out.rb
@@ -118,7 +118,7 @@ class Chef
       end
 
       def deprecate_option(old_option, new_option)
-        Chef.log_deprecation "DEPRECATION: Chef::Mixin::ShellOut option :#{old_option} is deprecated. Use :#{new_option}"
+        Chef.deprecated :internal_api, "Chef::Mixin::ShellOut option :#{old_option} is deprecated. Use :#{new_option}"
       end
 
       def io_for_live_stream
diff --git a/lib/chef/node.rb b/lib/chef/node.rb
index 7351a7bfa5..f2a5cab1f5 100644
--- a/lib/chef/node.rb
+++ b/lib/chef/node.rb
@@ -201,7 +201,7 @@ class Chef
     end
 
     def set
-      Chef.log_deprecation("node.set is deprecated and will be removed in Chef 14, please use node.default/node.override (or node.normal only if you really need persistence)")
+      Chef.deprecated(:attributes, "node.set is deprecated and will be removed in Chef 14, please use node.default/node.override (or node.normal only if you really need persistence)")
       normal
     end
 
@@ -509,7 +509,7 @@ class Chef
 
     # Create a Chef::Node from JSON
     def self.json_create(o)
-      Chef.log_deprecation("Auto inflation of JSON data is deprecated. Please use Chef::Node#from_hash")
+      Chef.deprecated(:json_auto_inflate, "Auto inflation of JSON data is deprecated. Please use Chef::Node#from_hash")
       from_hash(o)
     end
 
diff --git a/lib/chef/node/attribute.rb b/lib/chef/node/attribute.rb
index 2ed32d50ad..d2816d4824 100644
--- a/lib/chef/node/attribute.rb
+++ b/lib/chef/node/attribute.rb
@@ -430,7 +430,7 @@ class Chef
       end
 
       def set_unless(*args)
-        Chef.log_deprecation("node.set_unless is deprecated and will be removed in Chef 14, please use node.default_unless/node.override_unless (or node.normal_unless if you really need persistence)")
+        Chef.deprecated(:attributes, "node.set_unless is deprecated and will be removed in Chef 14, please use node.default_unless/node.override_unless (or node.normal_unless if you really need persistence)")
         return Decorator::Unchain.new(self, :default_unless) unless args.length > 0
         write(:normal, *args) if read(*args[0...-1]).nil?
       end
@@ -481,14 +481,14 @@ class Chef
         if symbol == :to_ary
           merged_attributes.send(symbol, *args)
         elsif args.empty?
-          Chef.log_deprecation %q{method access to node attributes (node.foo.bar) is deprecated and will be removed in Chef 13, please use bracket syntax (node["foo"]["bar"])}
+          Chef.deprecated(:attributes, %q{method access to node attributes (node.foo.bar) is deprecated and will be removed in Chef 13, please use bracket syntax (node["foo"]["bar"])})
           if key?(symbol)
             self[symbol]
           else
             raise NoMethodError, "Undefined method or attribute `#{symbol}' on `node'"
           end
         elsif symbol.to_s =~ /=$/
-          Chef.log_deprecation %q{method setting of node attributes (node.foo="bar") is deprecated and will be removed in Chef 13, please use bracket syntax (node["foo"]="bar")}
+          Chef.deprecated(:attributes, %q{method setting of node attributes (node.foo="bar") is deprecated and will be removed in Chef 13, please use bracket syntax (node["foo"]="bar")})
           key_to_set = symbol.to_s[/^(.+)=$/, 1]
           self[key_to_set] = (args.length == 1 ? args[0] : args)
         else
diff --git a/lib/chef/node_map.rb b/lib/chef/node_map.rb
index 5eac63d380..9e64ccadc0 100644
--- a/lib/chef/node_map.rb
+++ b/lib/chef/node_map.rb
@@ -32,8 +32,8 @@ class Chef
     # @return [NodeMap] Returns self for possible chaining
     #
     def set(key, value, platform: nil, platform_version: nil, platform_family: nil, os: nil, on_platform: nil, on_platforms: nil, canonical: nil, override: nil, &block)
-      Chef.log_deprecation("The on_platform option to node_map has been deprecated") if on_platform
-      Chef.log_deprecation("The on_platforms option to node_map has been deprecated") if on_platforms
+      Chef.deprecated(:internal_api, "The on_platform option to node_map has been deprecated") if on_platform
+      Chef.deprecated(:internal_api, "The on_platforms option to node_map has been deprecated") if on_platforms
       platform ||= on_platform || on_platforms
       filters = {}
       filters[:platform] = platform if platform
diff --git a/lib/chef/org.rb b/lib/chef/org.rb
index a148e37aea..cf6f605370 100644
--- a/lib/chef/org.rb
+++ b/lib/chef/org.rb
@@ -125,7 +125,7 @@ class Chef
     end
 
     def self.json_create(json)
-      Chef.log_deprecation("Auto inflation of JSON data is deprecated. Please use Chef::Org#from_json or Chef::Org#load.")
+      Chef.deprecated(:json_auto_inflate, "Auto inflation of JSON data is deprecated. Please use Chef::Org#from_json or Chef::Org#load.")
       Chef::Org.from_json(json)
     end
 
diff --git a/lib/chef/policy_builder/expand_node_object.rb b/lib/chef/policy_builder/expand_node_object.rb
index df6956cc77..d8f4f752de 100644
--- a/lib/chef/policy_builder/expand_node_object.rb
+++ b/lib/chef/policy_builder/expand_node_object.rb
@@ -112,7 +112,7 @@ class Chef
       # to create a PolicyBuilder::Dynamc policy builder and allow it to select
       # the proper implementation.
       def load_node
-        Chef.log_deprecation("ExpandNodeObject#load_node is deprecated. Please use Chef::PolicyBuilder::Dynamic instead of using ExpandNodeObject directly")
+        Chef.deprecated(:internal_api, "ExpandNodeObject#load_node is deprecated. Please use Chef::PolicyBuilder::Dynamic instead of using ExpandNodeObject directly")
 
         events.node_load_start(node_name, config)
         Chef::Log.debug("Building node object for #{node_name}")
diff --git a/lib/chef/property.rb b/lib/chef/property.rb
index 9433326b5b..8d8ed352b3 100644
--- a/lib/chef/property.rb
+++ b/lib/chef/property.rb
@@ -116,7 +116,7 @@ class Chef
           options.delete(:name_property)
           preferred_default = :default
         end
-        Chef.log_deprecation("Cannot specify both default and name_property together on property #{self}. Only one (#{preferred_default}) will be obeyed. In Chef 13, this will become an error. Please remove one or the other from the property.")
+        Chef.deprecated(:custom_resource, "Cannot specify both default and name_property together on property #{self}. Only one (#{preferred_default}) will be obeyed. In Chef 13, this will become an error. Please remove one or the other from the property.")
       end
 
       # Validate the default early, so the user gets a good error message, and
@@ -287,13 +287,13 @@ class Chef
           input_to_stored_value(resource, value)
           # If nil is valid, and it would change the value, warn that this will change to a set.
           if !result.nil?
-            Chef.log_deprecation("An attempt was made to change #{name} from #{result.inspect} to nil by calling #{name}(nil). In Chef 12, this does a get rather than a set. In Chef 13, this will change to set the value to nil.")
+            Chef.deprecated(:custom_resource, "An attempt was made to change #{name} from #{result.inspect} to nil by calling #{name}(nil). In Chef 12, this does a get rather than a set. In Chef 13, this will change to set the value to nil.")
           end
         rescue Chef::Exceptions::DeprecatedFeatureError
           raise
         rescue
           # If nil is invalid, warn that this will become an error.
-          Chef.log_deprecation("nil is an invalid value for #{self}. In Chef 13, this warning will change to an error. Error: #{$!}")
+          Chef.deprecated(:custom_resource, "nil is an invalid value for #{self}. In Chef 13, this warning will change to an error. Error: #{$!}")
         end
 
         result
@@ -677,9 +677,9 @@ class Chef
         # warn and return the (possibly coerced) value to the user.
         if is_default
           if value.nil?
-            Chef.log_deprecation("Default value nil is invalid for property #{self}. Possible fixes: 1. Remove 'default: nil' if nil means 'undefined'. 2. Set a valid default value if there is a reasonable one. 3. Allow nil as a valid value of your property (for example, 'property #{name.inspect}, [ String, nil ], default: nil'). Error: #{$!}")
+            Chef.deprecated(:custom_resource, "Default value nil is invalid for property #{self}. Possible fixes: 1. Remove 'default: nil' if nil means 'undefined'. 2. Set a valid default value if there is a reasonable one. 3. Allow nil as a valid value of your property (for example, 'property #{name.inspect}, [ String, nil ], default: nil'). Error: #{$!}")
           else
-            Chef.log_deprecation("Default value #{value.inspect} is invalid for property #{self}. In Chef 13 this will become an error: #{$!}.")
+            Chef.deprecated(:custom_resource, "Default value #{value.inspect} is invalid for property #{self}. In Chef 13 this will become an error: #{$!}.")
           end
         else
           raise
diff --git a/lib/chef/provider.rb b/lib/chef/provider.rb
index 399a26aca0..40c31e4371 100644
--- a/lib/chef/provider.rb
+++ b/lib/chef/provider.rb
@@ -424,7 +424,7 @@ class Chef
     module DeprecatedLWRPClass
       def const_missing(class_name)
         if Chef::Provider.deprecated_constants[class_name.to_sym]
-          Chef.log_deprecation("Using an LWRP provider by its name (#{class_name}) directly is no longer supported in Chef 12 and will be removed.  Use Chef::ProviderResolver.new(node, resource, action) instead.")
+          Chef.deprecated(:custom_resource, "Using an LWRP provider by its name (#{class_name}) directly is no longer supported in Chef 12 and will be removed.  Use Chef::ProviderResolver.new(node, resource, action) instead.")
           Chef::Provider.deprecated_constants[class_name.to_sym]
         else
           raise NameError, "uninitialized constant Chef::Provider::#{class_name}"
diff --git a/lib/chef/provider/package/easy_install.rb b/lib/chef/provider/package/easy_install.rb
index 989f2ab9d2..926f609092 100644
--- a/lib/chef/provider/package/easy_install.rb
+++ b/lib/chef/provider/package/easy_install.rb
@@ -112,7 +112,7 @@ class Chef
         end
 
         def install_package(name, version)
-          Chef.log_deprecation("The easy_install package provider is deprecated and will be removed in Chef 13.")
+          Chef.deprecated(:easy_install, "The easy_install package provider is deprecated and will be removed in Chef 13.")
           run_command(:command => "#{easy_install_binary_path}#{expand_options(@new_resource.options)} \"#{name}==#{version}\"")
         end
 
@@ -121,7 +121,7 @@ class Chef
         end
 
         def remove_package(name, version)
-          Chef.log_deprecation("The easy_install package provider is deprecated and will be removed in Chef 13.")
+          Chef.deprecated(:easy_install, "The easy_install package provider is deprecated and will be removed in Chef 13.")
           run_command(:command => "#{easy_install_binary_path }#{expand_options(@new_resource.options)} -m #{name}")
         end
 
diff --git a/lib/chef/provider_resolver.rb b/lib/chef/provider_resolver.rb
index 1df473abbd..8903f65d26 100644
--- a/lib/chef/provider_resolver.rb
+++ b/lib/chef/provider_resolver.rb
@@ -157,8 +157,8 @@ class Chef
             # perf concern otherwise.)
             handlers = providers.select { |handler| overrode_provides?(handler) && handler.provides?(node, resource) }
             handlers.each do |handler|
-              Chef.log_deprecation("#{handler}.provides? returned true when asked if it provides DSL #{resource.resource_name}, but provides #{resource.resource_name.inspect} was never called!")
-              Chef.log_deprecation("In Chef 13, this will break: you must call provides to mark the names you provide, even if you also override provides? yourself.")
+              message = "#{handler}.provides? returned true when asked if it provides DSL #{resource.resource_name}, but provides #{resource.resource_name.inspect} was never called!  In Chef 13, this will break: you must call provides to mark the names you provide, even if you also override provides? yourself."
+              Chef.deprecated(:custom_resource, message)
             end
           end
           handlers
diff --git a/lib/chef/resource.rb b/lib/chef/resource.rb
index 074ab772a1..cde202dcf2 100644
--- a/lib/chef/resource.rb
+++ b/lib/chef/resource.rb
@@ -925,9 +925,7 @@ class Chef
     # @deprecated Multiple actions are supported by resources.  Please call {}#updated_by_last_action} instead.
     #
     def updated=(true_or_false)
-      Chef::Log.warn("Chef::Resource#updated=(true|false) is deprecated. Please call #updated_by_last_action(true|false) instead.")
-      Chef::Log.warn("Called from:")
-      caller[0..3].each { |line| Chef::Log.warn(line) }
+      Chef.deprecated(:custom_resource, "Chef::Resource#updated=(true|false) is deprecated. Please call #updated_by_last_action(true|false) instead.")
       updated_by_last_action(true_or_false)
       @updated = true_or_false
     end
@@ -982,7 +980,7 @@ class Chef
     # @deprecated Use resource_name instead.
     #
     def self.dsl_name
-      Chef.log_deprecation "Resource.dsl_name is deprecated and will be removed in Chef 13.  Use resource_name instead."
+      Chef.deprecated(:custom_resource, "Resource.dsl_name is deprecated and will be removed in Chef 13.  Use resource_name instead.")
       if name
         name = self.name.split("::")[-1]
         convert_to_snake_case(name)
@@ -1060,7 +1058,7 @@ class Chef
     #
     def self.provider_base(arg = nil)
       if arg
-        Chef.log_deprecation("Resource.provider_base is deprecated and will be removed in Chef 13. Use provides on the provider, or provider on the resource, instead.")
+        Chef.deprecated(:custom_resource, "Resource.provider_base is deprecated and will be removed in Chef 13. Use provides on the provider, or provider on the resource, instead.")
       end
       @provider_base ||= arg || Chef::Provider
     end
diff --git a/lib/chef/resource/chef_gem.rb b/lib/chef/resource/chef_gem.rb
index 4445bf0f89..c7c6d91752 100644
--- a/lib/chef/resource/chef_gem.rb
+++ b/lib/chef/resource/chef_gem.rb
@@ -34,9 +34,8 @@ class Chef
         # Chef::Resource.run_action: Caveat: this skips Chef::Runner.run_action, where notifications are handled
         # Action could be an array of symbols, but probably won't (think install + enable for a package)
         if compile_time.nil?
-          Chef.log_deprecation "#{self} chef_gem compile_time installation is deprecated"
-          Chef.log_deprecation "#{self} Please set `compile_time false` on the resource to use the new behavior."
-          Chef.log_deprecation "#{self} or set `compile_time true` on the resource if compile_time behavior is required."
+          message = "#{self} chef_gem compile_time installation is deprecated. Please set `compile_time false` on the resource to use the new behavior, or set `compile_time true` on the resource if compile_time behavior is required."
+          Chef.deprecated :chef_gem_compile_time, message
         end
 
         if compile_time || compile_time.nil?
diff --git a/lib/chef/resource/file/verification.rb b/lib/chef/resource/file/verification.rb
index e11035d33f..cf5585e5cf 100644
--- a/lib/chef/resource/file/verification.rb
+++ b/lib/chef/resource/file/verification.rb
@@ -108,7 +108,7 @@ class Chef
         def verify_command(path, opts)
           # First implementation interpolated `file`; docs & RFC claim `path`
           # is interpolated. Until `file` can be deprecated, interpolate both.
-          Chef.log_deprecation(
+          Chef.deprecated(:verify_file,
             "%{file} is deprecated in verify command and will not be "\
             "supported in Chef 13. Please use %{path} instead."
           ) if @command.include?("%{file}")
diff --git a/lib/chef/resource/user.rb b/lib/chef/resource/user.rb
index 06dfe95bd4..19a4e2faf5 100644
--- a/lib/chef/resource/user.rb
+++ b/lib/chef/resource/user.rb
@@ -158,10 +158,10 @@ class Chef
 
       def supports(args = {})
         if args.key?(:manage_home)
-          Chef.log_deprecation "supports { manage_home: #{args[:manage_home]} } on the user resource is deprecated and will be removed in Chef 13, set manage_home: #{args[:manage_home]} instead"
+          Chef.deprecated(:supports_property, "supports { manage_home: #{args[:manage_home]} } on the user resource is deprecated and will be removed in Chef 13, set manage_home: #{args[:manage_home]} instead")
         end
         if args.key?(:non_unique)
-          Chef.log_deprecation "supports { non_unique: #{args[:non_unique]} } on the user resource is deprecated and will be removed in Chef 13, set non_unique: #{args[:non_unique]} instead"
+          Chef.deprecated(:supports_property, "supports { non_unique: #{args[:non_unique]} } on the user resource is deprecated and will be removed in Chef 13, set non_unique: #{args[:non_unique]} instead")
         end
         super
       end
diff --git a/lib/chef/resource_builder.rb b/lib/chef/resource_builder.rb
index 57c57dd8c3..78b2fcd4d1 100644
--- a/lib/chef/resource_builder.rb
+++ b/lib/chef/resource_builder.rb
@@ -128,10 +128,10 @@ class Chef
     end
 
     def emit_cloned_resource_warning
-      message = "Cloning resource attributes for #{resource} from prior resource (CHEF-3694)"
+      message = "Cloning resource attributes for #{resource} from prior resource"
       message << "\nPrevious #{prior_resource}: #{prior_resource.source_line}" if prior_resource.source_line
       message << "\nCurrent  #{resource}: #{resource.source_line}" if resource.source_line
-      Chef.log_deprecation(message)
+      Chef.deprecated(:resource_cloning, message)
     end
 
     def emit_harmless_cloning_debug
diff --git a/lib/chef/resource_resolver.rb b/lib/chef/resource_resolver.rb
index 769272d637..fca6c6db81 100644
--- a/lib/chef/resource_resolver.rb
+++ b/lib/chef/resource_resolver.rb
@@ -55,7 +55,7 @@ class Chef
     attr_reader :resource_name
     # @api private
     def resource
-      Chef.log_deprecation("Chef::ResourceResolver.resource deprecated.  Use resource_name instead.")
+      Chef.deprecated(:custom_resource, "Chef::ResourceResolver.resource deprecated.  Use resource_name instead.")
       resource_name
     end
     # @api private
@@ -173,8 +173,7 @@ class Chef
         if handlers.empty?
           handlers = resources.select { |handler| overrode_provides?(handler) && handler.provides?(node, resource_name) }
           handlers.each do |handler|
-            Chef.log_deprecation("#{handler}.provides? returned true when asked if it provides DSL #{resource_name}, but provides #{resource_name.inspect} was never called!")
-            Chef.log_deprecation("In Chef 13, this will break: you must call provides to mark the names you provide, even if you also override provides? yourself.")
+            Chef.deprecated(:custom_resource, "#{handler}.provides? returned true when asked if it provides DSL #{resource_name}, but provides #{resource_name.inspect} was never called! In Chef 13, this will break: you must call provides to mark the names you provide, even if you also override provides? yourself.")
           end
         end
         handlers
diff --git a/lib/chef/rest.rb b/lib/chef/rest.rb
index b3793418ce..0705ca9f5a 100644
--- a/lib/chef/rest.rb
+++ b/lib/chef/rest.rb
@@ -59,7 +59,7 @@ class Chef
     # http://localhost:4000, a call to +get_rest+ with 'nodes' will make an
     # HTTP GET request to http://localhost:4000/nodes
     def initialize(url, client_name = Chef::Config[:node_name], signing_key_filename = Chef::Config[:client_key], options = {})
-      Chef.log_deprecation("Chef::REST is deprecated. Please use Chef::ServerAPI, or investigate Ridley or ChefAPI.")
+      Chef.deprecated(:chef_rest, "Chef::REST is deprecated. Please use Chef::ServerAPI, or investigate Ridley or ChefAPI.")
 
       signing_key_filename = nil if chef_zero_uri?(url)
 
diff --git a/lib/chef/role.rb b/lib/chef/role.rb
index 331fa614f1..218894ef03 100644
--- a/lib/chef/role.rb
+++ b/lib/chef/role.rb
@@ -170,7 +170,7 @@ class Chef
 
     # Create a Chef::Role from JSON
     def self.json_create(o)
-      Chef.log_deprecation("Auto inflation of JSON data is deprecated. Please use Chef::Role#from_hash")
+      Chef.deprecated(:json_auto_inflate, "Auto inflation of JSON data is deprecated. Please use Chef::Role#from_hash")
       from_hash(o)
     end
 
diff --git a/lib/chef/run_context.rb b/lib/chef/run_context.rb
index 626977b09f..aa6280e5be 100644
--- a/lib/chef/run_context.rb
+++ b/lib/chef/run_context.rb
@@ -581,17 +581,17 @@ ERROR_MESSAGE
       # These need to be settable so deploy can run a resource_collection
       # independent of any cookbooks via +recipe_eval+
       def audits=(value)
-        Chef.log_deprecation("Setting run_context.audits will be removed in a future Chef.  Use run_context.create_child to create a new RunContext instead.")
+        Chef.deprecated(:internal_api, "Setting run_context.audits will be removed in a future Chef.  Use run_context.create_child to create a new RunContext instead.")
         @audits = value
       end
 
       def immediate_notification_collection=(value)
-        Chef.log_deprecation("Setting run_context.immediate_notification_collection will be removed in a future Chef.  Use run_context.create_child to create a new RunContext instead.")
+        Chef.deprecated(:internal_api, "Setting run_context.immediate_notification_collection will be removed in a future Chef.  Use run_context.create_child to create a new RunContext instead.")
         @immediate_notification_collection = value
       end
 
       def delayed_notification_collection=(value)
-        Chef.log_deprecation("Setting run_context.delayed_notification_collection will be removed in a future Chef.  Use run_context.create_child to create a new RunContext instead.")
+        Chef.deprecated(:internal_api, "Setting run_context.delayed_notification_collection will be removed in a future Chef.  Use run_context.create_child to create a new RunContext instead.")
         @delayed_notification_collection = value
       end
     end
diff --git a/lib/chef/user.rb b/lib/chef/user.rb
index a6fc21646d..261ce43ef2 100644
--- a/lib/chef/user.rb
+++ b/lib/chef/user.rb
@@ -26,13 +26,13 @@ require "chef/server_api"
 # TODO
 # DEPRECATION NOTE
 # This class will be replaced by Chef::UserV1 in Chef 13. It is the code to support the User object
-# corrosponding to the Open Source Chef Server 11 and only still exists to support
+# corresponding to the Open Source Chef Server 11 and only still exists to support
 # users still on OSC 11.
 #
 # Chef::UserV1 now supports Chef Server 12 and will be moved to this namespace in Chef 13.
 #
 # New development should occur in Chef::UserV1.
-# This file and corrosponding osc_user knife files
+# This file and corresponding osc_user knife files
 # should be removed once client support for Open Source Chef Server 11 expires.
 class Chef
   class User
@@ -155,7 +155,7 @@ class Chef
     end
 
     def self.json_create(json)
-      Chef.log_deprecation("Auto inflation of JSON data is deprecated. Please use Chef::User#from_json or Chef::User#load.")
+      Chef.deprecated(:json_auto_inflate, "Auto inflation of JSON data is deprecated. Please use Chef::User#from_json or Chef::User#load.")
       Chef::User.from_json(json)
     end
 
diff --git a/lib/chef/user_v1.rb b/lib/chef/user_v1.rb
index db44ced9d4..fc01057888 100644
--- a/lib/chef/user_v1.rb
+++ b/lib/chef/user_v1.rb
@@ -277,7 +277,7 @@ class Chef
     end
 
     def self.json_create(json)
-      Chef.log_deprecation("Auto inflation of JSON data is deprecated. Please use Chef::UserV1#from_json or Chef::UserV1#load.")
+      Chef.deprecated(:json_auto_inflate, "Auto inflation of JSON data is deprecated. Please use Chef::UserV1#from_json or Chef::UserV1#load.")
       Chef::UserV1.from_json(json)
     end
 
diff --git a/spec/unit/application/exit_code_spec.rb b/spec/unit/application/exit_code_spec.rb
index 59ee400c23..5abf19fc02 100644
--- a/spec/unit/application/exit_code_spec.rb
+++ b/spec/unit/application/exit_code_spec.rb
@@ -77,11 +77,7 @@ describe Chef::Application::ExitCode do
     end
 
     it "writes a deprecation warning" do
-      warn = "Chef RFC 062 (https://github.com/chef/chef-rfc/master/rfc062-exit-status.md) defines the" \
-      " exit codes that should be used with Chef.  Chef::Application::ExitCode defines valid exit codes"  \
-      " In a future release, non-standard exit codes will be redefined as" \
-      " GENERIC_FAILURE unless `exit_status` is set to `:disabled` in your client.rb."
-      expect(Chef).to receive(:log_deprecation).with(warn)
+      expect(Chef).to receive(:deprecated).with(:exit_code, /^Chef RFC 062/)
       expect(exit_codes.normalize_exit_code(151)).to eq(151)
     end
 
@@ -118,11 +114,7 @@ describe Chef::Application::ExitCode do
     end
 
     it "does not write a deprecation warning" do
-      warn = "Chef RFC 062 (https://github.com/chef/chef-rfc/master/rfc062-exit-status.md) defines the" \
-      " exit codes that should be used with Chef.  Chef::Application::ExitCode defines valid exit codes"  \
-      " In a future release, non-standard exit codes will be redefined as" \
-      " GENERIC_FAILURE unless `exit_status` is set to `:disabled` in your client.rb."
-      expect(Chef).not_to receive(:log_deprecation).with(warn)
+      expect(Chef).not_to receive(:deprecated).with(:exit_code, /^Chef RFC 062/)
       expect(exit_codes.normalize_exit_code(151)).to eq(151)
     end
 
@@ -163,11 +155,7 @@ describe Chef::Application::ExitCode do
     end
 
     it "does write a deprecation warning" do
-      warn = "Chef RFC 062 (https://github.com/chef/chef-rfc/master/rfc062-exit-status.md) defines the" \
-      " exit codes that should be used with Chef.  Chef::Application::ExitCode defines valid exit codes"  \
-      " In a future release, non-standard exit codes will be redefined as" \
-      " GENERIC_FAILURE unless `exit_status` is set to `:disabled` in your client.rb."
-      expect(Chef).to receive(:log_deprecation).with(warn)
+      expect(Chef).to receive(:deprecated).with(:exit_code, /^Chef RFC 062/)
       expect(exit_codes.normalize_exit_code(151)).to eq(1)
     end
 
diff --git a/spec/unit/deprecated_spec.rb b/spec/unit/deprecated_spec.rb
new file mode 100644
index 0000000000..9be792ab20
--- /dev/null
+++ b/spec/unit/deprecated_spec.rb
@@ -0,0 +1,59 @@
+#
+# Copyright:: Copyright 2013-2016, Chef Software Inc.
+# License:: Apache License, Version 2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+require "spec_helper"
+require "chef/deprecated"
+
+describe Chef::Deprecated do
+  class TestDeprecation < Chef::Deprecated::Base
+    def id; 999; end
+
+    def target; "test.html"; end
+
+    def link; "#{Chef::Deprecated::Base::BASE_URL}test.html"; end
+  end
+
+  context "loading a deprecation class" do
+    it "loads the correct class" do
+      expect(Chef::Deprecated.create(:test_deprecation)).to be_an_instance_of(Chef::Deprecated::TestDeprecation)
+    end
+
+    it "optionally sets a message" do
+      deprecation = Chef::Deprecated.create(:test_deprecation, "A test message")
+      expect(deprecation.message).to eql("A test message")
+    end
+
+    it "optionally sets the location" do
+      deprecation = Chef::Deprecated.create(:test_deprecation, nil, "A test location")
+      expect(deprecation.location).to eql("A test location")
+    end
+  end
+
+  context "formatting deprecation warnings" do
+    let(:base_url) { Chef::Deprecated::Base::BASE_URL }
+    let(:message) { "A test message" }
+    let(:location) { "the location" }
+
+    it "displays the full URL" do
+      expect(Chef::Deprecated::TestDeprecation.new().url).to eql("#{base_url}test.html")
+    end
+
+    it "formats a complete deprecation message" do
+      expect(Chef::Deprecated::TestDeprecation.new(message, location).inspect).to eql("#{message} (CHEF-999)#{location}.\nhttps://docs.chef.io/deprecations_test.html")
+    end
+  end
+end
diff --git a/spec/unit/deprecation_spec.rb b/spec/unit/deprecation_spec.rb
index af8e34850b..41c1724e5b 100644
--- a/spec/unit/deprecation_spec.rb
+++ b/spec/unit/deprecation_spec.rb
@@ -65,15 +65,8 @@ describe Chef::Deprecation do
     end
 
     context "deprecation warning messages" do
-      RSpec::Matchers.define_negated_matcher :a_non_empty_array, :be_empty
-
       it "should be enabled for deprecated methods" do
-        expect(Chef::Log).to receive(:warn).with(a_non_empty_array)
-        TestClass.new.deprecated_method(10)
-      end
-
-      it "should contain stack trace" do
-        expect(Chef::Log).to receive(:warn).with(a_string_including(".rb"))
+        expect(Chef).to receive(:deprecated).with(:internal_api, /Method.*of 'TestClass'/)
         TestClass.new.deprecated_method(10)
       end
     end
diff --git a/spec/unit/handler_spec.rb b/spec/unit/handler_spec.rb
index a56645fa78..09dd99d1ee 100644
--- a/spec/unit/handler_spec.rb
+++ b/spec/unit/handler_spec.rb
@@ -37,7 +37,7 @@ describe Chef::Handler do
       @run_status.exception = @exception
       @run_context = Chef::RunContext.new(@node, {}, @events)
       @all_resources = [Chef::Resource::Cat.new("lolz"), Chef::Resource::ZenMaster.new("tzu")]
-      @all_resources.first.updated = true
+      @all_resources.first.updated_by_last_action true
       @run_context.resource_collection.all_resources.replace(@all_resources)
       @run_status.run_context = @run_context
       @start_time = Time.now
@@ -118,7 +118,7 @@ describe Chef::Handler do
     before do
       @run_context = Chef::RunContext.new(@node, {}, @events)
       @all_resources = [Chef::Resource::Cat.new("foo"), Chef::Resource::ZenMaster.new("moo")]
-      @all_resources.first.updated = true
+      @all_resources.first.updated_by_last_action true
       @run_context.resource_collection.all_resources.replace(@all_resources)
       @run_status.run_context = @run_context
       @start_time = Time.now
diff --git a/spec/unit/mixin/shell_out_spec.rb b/spec/unit/mixin/shell_out_spec.rb
index bf74ff410e..aa38639c1c 100644
--- a/spec/unit/mixin/shell_out_spec.rb
+++ b/spec/unit/mixin/shell_out_spec.rb
@@ -59,7 +59,6 @@ describe Chef::Mixin::ShellOut do
       it "should emit a deprecation warning" do
         assume_deprecation_log_level && capture_log_output
         subject
-        expect(output.string).to match /DEPRECATION:/
         expect(output.string).to match Regexp.escape(old_option.to_s)
         expect(output.string).to match Regexp.escape(new_option.to_s)
       end
diff --git a/spec/unit/node_spec.rb b/spec/unit/node_spec.rb
index cfc19db480..59b4b8a1c7 100644
--- a/spec/unit/node_spec.rb
+++ b/spec/unit/node_spec.rb
@@ -335,14 +335,14 @@ describe Chef::Node do
 
       it "set is a deprecated alias for normal" do
         Chef::Config[:treat_deprecation_warnings_as_errors] = false
-        expect(Chef).to receive(:log_deprecation).with(/set is deprecated/)
+        expect(Chef).to receive(:deprecated).with(:attributes, /set is deprecated/)
         node.set[:snoopy][:is_a_puppy] = true
         expect(node[:snoopy][:is_a_puppy]).to eq(true)
       end
 
       it "set_unless is a deprecated alias for normal_unless" do
         Chef::Config[:treat_deprecation_warnings_as_errors] = false
-        expect(Chef).to receive(:log_deprecation).with(/set_unless is deprecated/)
+        expect(Chef).to receive(:deprecated).with(:attributes, /set_unless is deprecated/)
         node.set_unless[:snoopy][:is_a_puppy] = false
         expect(node[:snoopy][:is_a_puppy]).to eq(false)
       end
diff --git a/spec/unit/provider/package/easy_install_spec.rb b/spec/unit/provider/package/easy_install_spec.rb
index fa5eea00a2..51d95c6968 100644
--- a/spec/unit/provider/package/easy_install_spec.rb
+++ b/spec/unit/provider/package/easy_install_spec.rb
@@ -61,7 +61,7 @@ describe Chef::Provider::Package::EasyInstall do
 
   describe "actions_on_package" do
     it "should run easy_install with the package name and version" do
-      expect(Chef).to receive(:log_deprecation).with(/easy_install package provider is deprecated/)
+      expect(Chef).to receive(:deprecated).with(:easy_install, /easy_install package provider is deprecated/)
       expect(@provider).to receive(:run_command).with({
         :command => "easy_install \"boto==1.8d\"",
       })
@@ -69,7 +69,7 @@ describe Chef::Provider::Package::EasyInstall do
     end
 
     it "should run easy_install with the package name and version and specified options" do
-      expect(Chef).to receive(:log_deprecation).with(/easy_install package provider is deprecated/)
+      expect(Chef).to receive(:deprecated).with(:easy_install, /easy_install package provider is deprecated/)
       expect(@provider).to receive(:run_command).with({
         :command => "easy_install --always-unzip \"boto==1.8d\"",
       })
@@ -78,7 +78,7 @@ describe Chef::Provider::Package::EasyInstall do
     end
 
     it "should run easy_install with the package name and version" do
-      expect(Chef).to receive(:log_deprecation).with(/easy_install package provider is deprecated/)
+      expect(Chef).to receive(:deprecated).with(:easy_install, /easy_install package provider is deprecated/)
       expect(@provider).to receive(:run_command).with({
         :command => "easy_install \"boto==1.8d\"",
       })
@@ -86,7 +86,7 @@ describe Chef::Provider::Package::EasyInstall do
     end
 
     it "should run easy_install -m with the package name and version" do
-      expect(Chef).to receive(:log_deprecation).with(/easy_install package provider is deprecated/)
+      expect(Chef).to receive(:deprecated).with(:easy_install, /easy_install package provider is deprecated/)
       expect(@provider).to receive(:run_command).with({
         :command => "easy_install -m boto",
       })
@@ -94,7 +94,7 @@ describe Chef::Provider::Package::EasyInstall do
     end
 
     it "should run easy_install -m with the package name and version and specified options" do
-      expect(Chef).to receive(:log_deprecation).with(/easy_install package provider is deprecated/)
+      expect(Chef).to receive(:deprecated).with(:easy_install, /easy_install package provider is deprecated/)
       expect(@provider).to receive(:run_command).with({
         :command => "easy_install -x -m boto",
       })
@@ -103,7 +103,7 @@ describe Chef::Provider::Package::EasyInstall do
     end
 
     it "should run easy_install -m with the package name and version" do
-      expect(Chef).to receive(:log_deprecation).with(/easy_install package provider is deprecated/)
+      expect(Chef).to receive(:deprecated).with(:easy_install, /easy_install package provider is deprecated/)
       expect(@provider).to receive(:run_command).with({
         :command => "easy_install -m boto",
       })
diff --git a/spec/unit/provider/user/linux_spec.rb b/spec/unit/provider/user/linux_spec.rb
index 1c487c0de9..819dc5e0fe 100644
--- a/spec/unit/provider/user/linux_spec.rb
+++ b/spec/unit/provider/user/linux_spec.rb
@@ -69,7 +69,7 @@ describe Chef::Provider::User::Linux do
 
     it "throws a deprecation warning on setting supports[:manage_home]" do
       Chef::Config[:treat_deprecation_warnings_as_errors] = false
-      expect(Chef).to receive(:log_deprecation).with("supports { manage_home: true } on the user resource is deprecated and will be removed in Chef 13, set manage_home: true instead")
+      expect(Chef).to receive(:deprecated).with(:supports_property, "supports { manage_home: true } on the user resource is deprecated and will be removed in Chef 13, set manage_home: true instead")
       @new_resource.supports( { :manage_home => true } )
     end
 
diff --git a/spec/unit/recipe_spec.rb b/spec/unit/recipe_spec.rb
index f42b7563f5..eea1a41998 100644
--- a/spec/unit/recipe_spec.rb
+++ b/spec/unit/recipe_spec.rb
@@ -195,7 +195,7 @@ describe Chef::Recipe do
 
     describe "when cloning resources" do
       def expect_warning
-        expect(Chef).to receive(:log_deprecation).with(/^Cloning resource attributes for zen_master\[klopp\]/)
+        expect(Chef).to receive(:deprecated).with(:resource_cloning, /^Cloning resource attributes for zen_master\[klopp\]/)
       end
 
       it "should emit a 3694 warning when attributes change" do
@@ -242,7 +242,7 @@ describe Chef::Recipe do
 
       it "should not emit a 3694 warning for completely trivial resource cloning" do
         recipe.zen_master "klopp"
-        expect(Chef).to_not receive(:log_deprecation)
+        expect(Chef).to_not receive(:deprecated)
         recipe.zen_master "klopp"
       end
 
@@ -250,7 +250,7 @@ describe Chef::Recipe do
         recipe.zen_master "klopp" do
           action :nothing
         end
-        expect(Chef).to_not receive(:log_deprecation)
+        expect(Chef).to_not receive(:deprecated)
         recipe.zen_master "klopp" do
           action :score
         end
@@ -260,7 +260,7 @@ describe Chef::Recipe do
         recipe.zen_master "klopp" do
           action :score
         end
-        expect(Chef).to_not receive(:log_deprecation)
+        expect(Chef).to_not receive(:deprecated)
         recipe.zen_master "klopp" do
           action :nothing
         end
@@ -283,7 +283,7 @@ describe Chef::Recipe do
 
       it "does not emit 3694 when the name_property is unlazied by running it at compile_time" do
         recipe.coerced "string"
-        expect(Chef).to_not receive(:log_deprecation)
+        expect(Chef).to_not receive(:deprecated)
         recipe.coerced "string"
       end
 
@@ -319,7 +319,7 @@ describe Chef::Recipe do
       end
 
       it "will insert another resource if create_if_missing is not set (cloned resource as of Chef-12)" do
-        expect(Chef).to receive(:log_deprecation).with(/^Cloning resource attributes for zen_master\[klopp\]/)
+        expect(Chef).to receive(:deprecated).with(:resource_cloning, /^Cloning resource attributes for zen_master\[klopp\]/)
         zm_resource
         recipe.declare_resource(:zen_master, "klopp")
         expect(run_context.resource_collection.count).to eql(2)
@@ -442,18 +442,18 @@ describe Chef::Recipe do
       end
 
       it "copies attributes from the first resource" do
-        expect(Chef).to receive(:log_deprecation).with(/^Cloning resource attributes for zen_master\[klopp\]/)
+        expect(Chef).to receive(:deprecated).with(:resource_cloning, /^Cloning resource attributes for zen_master\[klopp\]/)
         expect(duplicated_resource.something).to eq("bvb09")
       end
 
       it "does not copy the action from the first resource" do
-        expect(Chef).to receive(:log_deprecation).with(/^Cloning resource attributes for zen_master\[klopp\]/)
+        expect(Chef).to receive(:deprecated).with(:resource_cloning, /^Cloning resource attributes for zen_master\[klopp\]/)
         expect(original_resource.action).to eq([:score])
         expect(duplicated_resource.action).to eq([:nothing])
       end
 
       it "does not copy the source location of the first resource" do
-        expect(Chef).to receive(:log_deprecation).with(/^Cloning resource attributes for zen_master\[klopp\]/)
+        expect(Chef).to receive(:deprecated).with(:resource_cloning, /^Cloning resource attributes for zen_master\[klopp\]/)
         # sanity check source location:
         expect(original_resource.source_line).to include(__FILE__)
         expect(duplicated_resource.source_line).to include(__FILE__)
@@ -462,12 +462,12 @@ describe Chef::Recipe do
       end
 
       it "sets the cookbook name on the cloned resource to that resource's cookbook" do
-        expect(Chef).to receive(:log_deprecation).with(/^Cloning resource attributes for zen_master\[klopp\]/)
+        expect(Chef).to receive(:deprecated).with(:resource_cloning, /^Cloning resource attributes for zen_master\[klopp\]/)
         expect(duplicated_resource.cookbook_name).to eq("second_cb")
       end
 
       it "sets the recipe name on the cloned resource to that resoure's recipe" do
-        expect(Chef).to receive(:log_deprecation).with(/^Cloning resource attributes for zen_master\[klopp\]/)
+        expect(Chef).to receive(:deprecated).with(:resource_cloning, /^Cloning resource attributes for zen_master\[klopp\]/)
         expect(duplicated_resource.recipe_name).to eq("second_recipe")
       end
 
diff --git a/spec/unit/resource/file/verification_spec.rb b/spec/unit/resource/file/verification_spec.rb
index bc51eccaef..6416bb3ad8 100644
--- a/spec/unit/resource/file/verification_spec.rb
+++ b/spec/unit/resource/file/verification_spec.rb
@@ -88,7 +88,7 @@ describe Chef::Resource::File::Verification do
       end
 
       it "warns about deprecation when \%{file} is used" do
-        expect(Chef::Log).to receive(:deprecation).with(/%{file} is deprecated/, /verification_spec\.rb/)
+        expect(Chef).to receive(:deprecated).with(:verify_file, /%{file} is deprecated/)
         test_command = platform_specific_verify_command("file")
         Chef::Resource::File::Verification.new(parent_resource, test_command, {})
           .verify(temp_path)
diff --git a/spec/unit/run_status_spec.rb b/spec/unit/run_status_spec.rb
index 6305b7497b..60717fb3a8 100644
--- a/spec/unit/run_status_spec.rb
+++ b/spec/unit/run_status_spec.rb
@@ -100,7 +100,7 @@ describe Chef::RunStatus do
 
       describe "and some have been updated" do
         before do
-          @all_resources.first.updated = true
+          @all_resources.first.updated_by_last_action true
         end
 
         it "lists the updated resources" do