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>

2 files changed, 24 insertions, 5 deletions

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