Structure deprecations with additional metadatatm/deprecation_with_url

This adds URLs to each class of deprecation, and correctly prints and
formats them for maximum user efficiency. We also provide the URL to the
data collector for Visibility to ingest.

Signed-off-by: Thom May <thom@chef.io>

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