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>

11 files changed, 87 insertions, 48 deletions

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